# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Sidekick for Max is a VS Code extension providing AI-powered inline completions, code transforms, commit messages, session monitoring, and more — using the user's existing Claude Max subscription or Anthropic API key. It also supports OpenCode and Codex CLI as inference and monitoring providers.

All extension source lives in `sidekick-vscode/`. The root directory contains only documentation and assets.

## Build & Development Commands

All commands run from `sidekick-vscode/`:

```bash
npm run compile      # Dev build with source maps (esbuild)
npm run build        # Production build, minified
npm run watch        # Watch mode for development
npm test             # Run all tests (Vitest)
npm run test:watch   # Watch mode for tests
npm run lint         # ESLint check
npm run lint:fix     # ESLint auto-fix
npm run package      # Create .vsix for distribution
```

Run a single test file: `npx vitest run src/services/ModelResolver.test.ts` (from `sidekick-vscode/`).

Press **F5** in VS Code with `sidekick-vscode/` open to launch the Extension Development Host.

### Documentation Site

The docs site uses **zensical** (not mkdocs). Config is in `mkdocs.yml` at the repo root, content in `docs/`.

```bash
zensical build --strict   # Build docs site (from repo root)
zensical serve            # Local dev server with hot reload
```

Do **not** use `mkdocs build` or `mkdocs serve` — use `zensical` instead.

## Architecture

### Build System (esbuild.js)

esbuild produces four bundles:

| Output | Format | Platform |
|--------|--------|----------|
| `out/extension.js` (from `src/extension.ts`) | CommonJS | Node.js |
| `out/webview/explain.js` | IIFE | Browser |
| `out/webview/error.js` | IIFE | Browser |
| `out/webview/dashboard.js` | IIFE | Browser |

Only `vscode` is externalized. All other dependencies (including `@anthropic-ai/claude-agent-sdk` and `@opencode-ai/sdk`) are bundled by esbuild. The `conditions: ['import']`, `banner`, and `define` settings in esbuild.js polyfill `import.meta.url` for ESM deps bundled into CJS.

### Dual Provider System

Two separate provider concepts exist:

1. **Inference providers** (`InferenceProviderId` in `src/types/inferenceProvider.ts`): `claude-max | claude-api | opencode | codex` — which service generates AI completions
2. **Session providers** (`SessionProvider` in `src/types/sessionProvider.ts`): `claude-code | opencode | codex` — which CLI agent's sessions to monitor

Both use auto-detection via `ProviderDetector` based on filesystem presence and most-recent mtime.

### ClaudeClient Interface

All inference clients implement `ClaudeClient` from `src/types.ts`:

```typescript
interface ClaudeClient {
  complete(prompt: string, options?: CompletionOptions): Promise<string>;
  isAvailable(): Promise<boolean>;
  dispose(): void;
}
```

`AuthService` is the central entry point — lazily initializes the correct client and routes all `complete()` calls.

### Model Resolution

`ModelResolver.resolveModel()` handles: `"auto"` → per-feature default tier (from `FEATURE_AUTO_TIERS`) → provider-specific model ID. Legacy names (`haiku`/`sonnet`/`opus`) map through `LEGACY_TIER_MAP`. Tiers (`fast`/`balanced`/`powerful`) map through `DEFAULT_MODEL_MAPPINGS`. Anything else passes through as a literal model ID.

### Session Monitoring Pipeline

```
CLI agent writes JSONL/DB files
  → SessionProvider (normalizes to ClaudeSessionEvent)
    → SessionMonitor (watches files, aggregates stats, emits events)
      → Dashboard / MindMap / KanbanBoard / TreeViews / Notifications
```

Provider implementations live in `src/services/providers/`. Each normalizes raw data into `ClaudeSessionEvent` format defined in `src/types/claudeSession.ts`.

### Request Management

- **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

### Key Source Locations

- **Entry point**: `src/extension.ts` — `activate()`, all command/provider registration
- **Core types**: `src/types.ts` (ClaudeClient, CompletionOptions), `src/types/` (per-feature types)
- **Prompt templates**: `src/utils/prompts.ts`, `src/utils/analysisPrompts.ts`, `src/utils/summaryPrompts.ts`
- **Inference clients**: `src/services/AuthService.ts`, `MaxSubscriptionClient.ts`, `ApiKeyClient.ts`, `OpenCodeClient.ts`, `CodexClient.ts` (spawns CLI directly, no SDK)
- **Session providers**: `src/services/providers/ClaudeCodeSessionProvider.ts`, `OpenCodeSessionProvider.ts`, `CodexSessionProvider.ts`
- **Webview UI**: `src/webview/` — vanilla TS, bundled as IIFE; Chart.js for dashboard, D3.js for mind map

### Persistence

Cross-session data stored in `~/.config/sidekick/`:
- `historical-data.json` — token/cost/tool usage stats
- `tasks/{projectSlug}.json` — kanban board carry-over
- `decisions/{projectSlug}.json` — decision log

## Sidekick CLI

The CLI reads from `~/.config/sidekick/` (same data as the VS Code extension). Build with `bash scripts/build-all.sh`. Source in `sidekick-shared/` (pure TS library) and `sidekick-cli/` (esbuild-bundled binary).

- **npm package**: `sidekick-agent-hub` — the **binary name** is `sidekick` (defined in `sidekick-cli/package.json` `bin` field), not `sidekick-agent-hub`
- **CLI discovery**: `SidekickCliService.ts` searches configured path → common paths (including nvm) → `which sidekick`
- **VS Code terminal launch gotcha**: `vscode.window.createTerminal({ shellPath })` bypasses shell init (`.bashrc`/`.zshrc`), so nvm/volta `node` is not in PATH. The service injects the CLI's bin directory into the terminal `env.PATH` to fix this.

## Testing

Tests use **Vitest** with co-located files (`Foo.ts` / `Foo.test.ts`). The `vscode` module must be mocked in test files using `vi.mock("vscode", ...)` since VS Code is not available in the test runner.

## Conventions

- **TypeScript**: `strict: true`, target ES2022, no tsc emission (`noEmit: true` — esbuild builds)
- **Linting**: ESLint 9 + typescript-eslint; `@typescript-eslint/no-explicit-any` is `warn`; unused vars prefixed with `_` are allowed
- **Commits**: Conventional Commits (`feat(scope):`, `fix(scope):`, etc.)
- **Branches**: `feature/`, `fix/`, `docs/`, `refactor/` prefixes
- **File naming**: PascalCase for classes/services, camelCase for utilities
- **Settings prefix**: All VS Code settings use `sidekick.*`

## Release Process

Releases are triggered by pushing a `v*` tag to `main`. The CI workflow (`.github/workflows/release.yml`) runs four jobs:

1. **Validate Version** — verifies tag is on `main` and all three `package.json` versions match the tag
2. **Publish VS Code Extension** — lint, test, package `.vsix`, upload as artifact, publish to Open VSX
3. **Publish CLI to npm** — build shared lib, test CLI, build CLI, publish to npm (skips if version already published)
4. **Create GitHub Release** — downloads `.vsix` artifact, extracts changelog section, creates release with `.vsix` attached

**Version bump checklist** (all must match the tag):
- `sidekick-vscode/package.json`
- `sidekick-cli/package.json`
- `sidekick-shared/package.json`
- `sidekick-cli/package-lock.json` and `sidekick-shared/package-lock.json` (run `npm install --package-lock-only` in each)

**Changelogs to update** (four total):
- `CHANGELOG.md` (root — full project)
- `sidekick-vscode/CHANGELOG.md` (extension-specific)
- `sidekick-cli/CHANGELOG.md` (CLI-specific)
- `docs/changelog.md` (documentation site)