Create Plugin

Create Plugin

This skill is the embedded class: a Go package compiled into Sidecar with its own Bubble Tea UI. If what you want is a tool's data in Sidecar — a searchable tab, rows that open into documents, panes beside a terminal — you almost certainly want a protocol plugin instead: an executable in any language answering five JSON methods, which Sidecar renders itself and which ships as a config entry rather than a Sidecar release. Read docs/guides/active/creating-plugins.md and stop here. Come back only when the screen itself is the point — a board, a queue, a layout the collection-and-document vocabulary cannot express — because everything below costs a release, a keymap pass, and a permanent place in the repository.

Architecture Overview

• Bubble Tea model: internal/app/model.go owns the active plugin index, dispatches key events, renders plugin views.
• Registry: internal/plugin/registry.go stores plugins, handles lifecycle with panic protection, keeps an unavailable map when Init fails (silent degradation).
• Plugin contract: internal/plugin/plugin.go defines the interface every plugin must satisfy.
• Context: internal/plugin/context.go provides WorkDir, ConfigDir, Adapters, EventBus, Logger, Epoch, and Keymap.
• Keymap: internal/keymap maps keys to command IDs. Footer/help reads bindings by context using Plugin.Commands() + Plugin.FocusContext().

Plugin Interface

Every plugin must implement all of these methods:

ID() string              // Stable kebab-case identifier
Name() string            // Short human label for headers/help
Icon() string            // Single-character glyph for tab strip
Init(ctx *Context) error // Lightweight setup; return error to degrade gracefully
Start() tea.Cmd          // Kick off async work (non-blocking)
Update(msg tea.Msg) (Plugin, tea.Cmd) // Pure state transition
View(width, height int) string        // Render within provided dimensions
IsFocused() bool         // Check focus state
SetFocused(bool)         // App calls this on tab switch
Commands() []plugin.Command           // Footer hints per context
FocusContext() string    // Current context name for keymap
Stop()                   // Idempotent cleanup

Optional: implement Diagnostics() []plugin.Diagnostic for the diagnostics overlay.

Lifecycle Order

1. Registration (cmd/sidecar/main.go): registry.Register(myplugin.New()). No work here.
2. Init: Detect prerequisites (repos, adapters, env vars). Use ctx.Logger for warnings. Return error to degrade gracefully.
3. Start: Batch initial commands with tea.Batch. Never block.
4. Update: Pattern-match on custom Msg types and tea.KeyMsg. Keep I/O in commands, not directly in Update.
5. View: Render only; no side-effects. Honor width/height.
6. Focus/Blur: SetFocused called on tab switch. Pause expensive work when unfocused.
7. Stop: Close watchers, timers, channels. Guard with sync.Once/flags.

Epoch Pattern (Stale Message Detection)

When switching projects/worktrees, async operations may deliver stale data. Use the epoch pattern:

Step 1: Add Epoch to message type

type MyDataLoadedMsg struct {
    Epoch uint64
    Data  string
    Err   error
}
func (m MyDataLoadedMsg) GetEpoch() uint64 { return m.Epoch }

Step 2: Capture epoch in command creators

func (p *Plugin) loadData() tea.Cmd {
    epoch := p.ctx.Epoch // Capture synchronously before closure
    return func() tea.Msg {
        data, err := fetchData()
        return MyDataLoadedMsg{Epoch: epoch, Data: data, Err: err}
    }
}

Step 3: Check staleness in Update

case MyDataLoadedMsg:
    if plugin.IsStale(p.ctx, msg) {
        return p, nil // Discard stale message
    }
    p.data = msg.Data

Apply this to any async message that fetches data from filesystem/external sources or updates project-specific state.

Keymap, Contexts, and Commands

• Define contexts mirroring your view modes (e.g., git-status, git-diff). Return the active one from FocusContext().
• Expose commands with matching contexts via Commands(). These power footer hints and help overlay.
• Add default bindings in internal/keymap/bindings.go.
• Keep command IDs stable (verbs preferred: open-file, toggle-diff-mode).

Command structure

plugin.Command{
    ID:       "stage-file",
    Name:     "Stage",           // Keep 1-2 words max
    Category: plugin.CategoryGit,
    Priority: 10,                // Lower = higher priority; 0 treated as 99
    Context:  "git-status",
}

Categories: CategoryNavigation, CategoryActions, CategoryView, CategorySearch, CategoryEdit, CategoryGit, CategorySystem

Context naming convention

• plugin-name for main view
• plugin-name-detail for detail/preview
• plugin-name-modal for modals
• plugin-name-search for search modes

Dynamic binding registration

func (p *Plugin) Init(ctx *plugin.Context) error {
    if ctx.Keymap != nil {
        ctx.Keymap.RegisterPluginBinding("g g", "go-to-top", "my-context")
    }
    return nil
}

Event Bus (Cross-Plugin Communication)

• Subscribe: ch := ctx.EventBus.Subscribe("topic") in Start(), forward messages into Update.
• Publish: ctx.EventBus.Publish("topic", event.NewEvent(event.TypeRefreshNeeded, "topic", payload)).
• Best-effort, buffered (size 16), drops when full. Design listeners to be resilient.