Architecture Overview¶

Build System (esbuild)¶

esbuild produces four bundles:

flowchart LR
    subgraph Sources
        EXT["src/extension.ts"]
        EXP["src/webview/explain.ts"]
        ERR["src/webview/error.ts"]
        DSH["src/webview/dashboard.ts"]
    end

    EXT -->|CommonJS · Node.js| O1["out/extension.js"]
    EXP -->|IIFE · Browser| O2["out/webview/explain.js"]
    ERR -->|IIFE · Browser| O3["out/webview/error.js"]
    DSH -->|IIFE · Browser| O4["out/webview/dashboard.js"]

Only vscode is externalized. All other dependencies (including @anthropic-ai/claude-agent-sdk and @opencode-ai/sdk) are bundled by esbuild.

Entry Point¶

src/extension.ts contains the activate() function which registers all commands, providers, and services.

Package Structure¶

sidekick-shared extracts the data access layer from the extension so it can be consumed by the CLI, third-party tools, and custom integrations. It is published as a standalone npm package (npm install sidekick-shared) with no VS Code dependencies. Key modules include Zod schemas for runtime JSONL validation, pure extractors (extractTokenUsage, extractToolCall, extractToolCalls), model info and pricing (getModelInfo, calculateCost, calculateCostWithProvenance, shortModelName, formatCost), a typed JsonlParser with optional schema validation, the single-poller QuotaPoller class with exponential backoff, and the higher-level MultiProviderQuotaService + CodexQuotaWatcher that coordinate Claude polling, peak-hours enrichment, and Codex rate-limit watching behind one typed { claude?, codex? } event stream.

Starting in 0.17.4, sidekick-shared ships typed subpath entries via a package.json exports map. Use sidekick-shared/browser for pure, filesystem-free helpers safe in webviews and browser bundles (context-window lookup, model parsing, cost math), and sidekick-shared/node for the Node-only pricing-catalog hydration API. The package root still exposes the full API for Node consumers, and legacy sidekick-shared/dist/* deep imports keep resolving via a compat entry — see the sidekick-shared README for the full import-path table.

Key Source Locations¶

Request Management¶

flowchart LR
    K["Keystroke"] --> D["Debounce<br/><small>1000ms default</small>"]
    D --> CC{"Cache\nhit?"}
    CC -->|Yes| R["Return cached"]
    CC -->|No| API["API Call<br/><small>AbortController · TimeoutManager</small>"]
    API --> CS["Store in cache<br/><small>LRU · 100 entries · 30s TTL</small>"]
    CS --> DI["Display completion"]

• Debouncing: Configurable delay (default 1000ms) before firing inline completion requests
• LRU cache: CompletionCache — 100 entries, 30s TTL
• Cancellation: AbortController linked through CompletionOptions.signal
• Timeouts: TimeoutManager provides per-operation timeouts with context-size scaling

Persistence¶

Cross-session data stored in ~/.config/sidekick/:

The Sidekick CLI reads from these same files, providing terminal access to persisted data without VS Code.