create-adapter

Create Adapter

Why Performance Matters

Adapters are the largest performance risk in Sidecar. Conversations refresh on watch events in a hot path that runs continuously during active sessions:

watch event -> coalescer -> session refresh -> adapter.Sessions() -> metadata parsing

If an adapter does full directory scans and full-file reparses on every change, CPU and FD usage spike quickly.

Reference Adapters

Study these before writing a new adapter:

• internal/adapter/claudecode - Incremental JSONL parsing, targeted refresh
• internal/adapter/codex - Directory cache, two-pass metadata parsing, global watch scope
• internal/adapter/cursor - SQLite/WAL-aware cache invalidation, FD-safe DB access
• internal/adapter/pi - Global scope, JSONL, CWD-based filtering, session classification, message prefix stripping

Required Interface

All adapters implement adapter.Adapter:

type Adapter interface {
    ID() string
    Name() string
    Icon() string
    Detect(projectRoot string) (bool, error)
    Capabilities() CapabilitySet
    Sessions(projectRoot string) ([]Session, error)
    Messages(sessionID string) ([]Message, error)
    Usage(sessionID string) (*UsageStats, error)
    Watch(projectRoot string) (<-chan Event, io.Closer, error)
}

Required Session Fields

Every session from Sessions() must set:

• ID, Name
• AdapterID, AdapterName, AdapterIcon
• CreatedAt, UpdatedAt
• MessageCount, FileSize

FileSize is used for dynamic debounce and huge-session auto-reload protection.

Treat source identity separately from lineage. Use the source's durable thread/session ID for Session.ID; parent, root, fork, or lineage IDs describe relationships and must not collapse distinct sessions. Decode metadata fields defensively when the source has emitted multiple shapes over time (for example, a string in one version and an object in another).

Path and Watch Strategy

Set Session.Path only when Sidecar should use tiered file watching for that adapter:

• File-based append-only (JSONL/log): set Path to absolute file path — this opts into TieredWatcher with HOT/COLD/FROZEN tiers
• DB/WAL adapters (Cursor, Warp, Kiro): prefer adapter-specific Watch() with WAL-aware invalidation; do not set Path unless tiered watching covers your write surface