AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to Codex and other coding agents when working with code in this repository. `CLAUDE.md` mirrors the same project guidance for Claude Code.
4 
5## Project Overview
6 
7Sidekick Agent Hub is an AI coding assistant with real-time agent monitoring. It ships as a VS Code extension and a terminal dashboard, using Claude Max, Claude API, OpenCode, or Codex CLI for inference and session monitoring.
8 
9The repo is a small monorepo:
10 
11- `sidekick-vscode/` — VS Code extension, extension-host services, and webview source
12- `sidekick-shared/` — shared TypeScript library used by the extension and CLI; published as `sidekick-shared`
13- `sidekick-cli/` — Ink-based terminal dashboard; published as `sidekick-agent-hub` with the `sidekick` binary
14- `docs/`, `mkdocs.yml`, `assets/`, `images/` — documentation site content and assets
15- `scripts/` — cross-package build, lint, and version helpers
16 
17## Build & Development Commands
18 
19Extension commands run from `sidekick-vscode/`:
20 
21```bash
22npm run compile      # Dev build with source maps (esbuild)
23npm run build        # Production build, minified
24npm run watch        # Watch mode for development
25npm test             # Run all tests (Vitest)
26npm run test:watch   # Watch mode for tests
27npm run lint         # ESLint check
28npm run lint:fix     # ESLint auto-fix
29npm run format       # Prettier write for this package
30npm run format:check # Prettier check for this package
31npm run package      # Create .vsix for distribution
32```
33 
34Run a single test file: `npx vitest run src/services/ModelResolver.test.ts` (from `sidekick-vscode/`).
35 
36Press **F5** in VS Code with `sidekick-vscode/` open to launch the Extension Development Host.
37 
38Shared library commands run from `sidekick-shared/`:
39 
40```bash
41npm run build        # tsc build to dist/
42npm test             # Build, then run Vitest
43npm run lint         # ESLint check
44npm run format       # Prettier write for this package
45npm run format:check # Prettier check for this package
46```
47 
48CLI commands run from `sidekick-cli/`:
49 
50```bash
51npm run build        # esbuild ESM binary to dist/sidekick-cli.mjs
52npm test             # Run Vitest
53npm run lint         # ESLint check
54npm run format       # Prettier write for this package
55npm run format:check # Prettier check for this package
56```
57 
58**Monorepo-wide helpers** (run from repo root) cover all three packages — `sidekick-shared`, `sidekick-vscode`, `sidekick-cli`:
59 
60```bash
61bash scripts/lint-all.sh          # Lint all three packages (CI lints each separately)
62bash scripts/lint-all.sh --fix    # Lint + auto-fix all three
63bash scripts/format-all.sh        # Prettier write across packages, docs, root markdown/YAML, and workflows
64bash scripts/format-check-all.sh  # Prettier check across packages, docs, root markdown/YAML, and workflows
65bash scripts/build-all.sh         # npm install + build all three; CLI binary at sidekick-cli/dist/sidekick-cli.mjs
66bash scripts/bump-version.sh X.Y.Z # Update package.json versions; sync lockfiles separately
67```
68 
69### Documentation Site
70 
71The docs site uses **zensical** (not mkdocs). Config is in `mkdocs.yml` at the repo root, content in `docs/`.
72 
73```bash
74zensical build --strict   # Build docs site (from repo root)
75zensical serve            # Local dev server with hot reload
76```
77 
78Do **not** use `mkdocs build` or `mkdocs serve` — use `zensical` instead.
79 
80## Architecture
81 
82### Build System (esbuild.js)
83 
84`sidekick-vscode/esbuild.js` produces five bundles:
85 
86| Output                                       | Format   | Platform |
87| -------------------------------------------- | -------- | -------- |
88| `out/extension.js` (from `src/extension.ts`) | CommonJS | Node.js  |
89| `out/webview/explain.js`                     | IIFE     | Browser  |
90| `out/webview/error.js`                       | IIFE     | Browser  |
91| `out/webview/chartjs-vendor.js`              | IIFE     | Browser  |
92| `out/webview/d3-vendor.js`                   | IIFE     | Browser  |
93 
94Only `vscode` is externalized from the extension-host bundle. Other extension dependencies (including `@anthropic-ai/claude-agent-sdk`, `@opencode-ai/sdk`, and `sidekick-shared`) are bundled by esbuild. The `conditions: ['import']`, `banner`, and `define` settings in `esbuild.js` polyfill `import.meta.url` for ESM deps bundled into CJS. Chart.js and D3.js are bundled into local browser vendor files so the dashboard and mind map work offline.
95 
96### Dual Provider System
97 
98Two separate provider concepts exist:
99 
1001. **Inference providers** (`InferenceProviderId` in `src/types/inferenceProvider.ts`): `claude-max | claude-api | opencode | codex` — which service generates AI completions
1012. **Session providers** (`SessionProvider` in `src/types/sessionProvider.ts`): `claude-code | opencode | codex` — which CLI agent's sessions to monitor
102 
103Both use auto-detection via `ProviderDetector` based on filesystem presence and most-recent mtime.
104 
105### ClaudeClient Interface
106 
107All inference clients implement `ClaudeClient` from `src/types.ts`:
108 
109```typescript
110interface ClaudeClient {
111  complete(prompt: string, options?: CompletionOptions): Promise<string>;
112  isAvailable(): Promise<boolean>;
113  dispose(): void;
114}
115```
116 
117`AuthService` is the central entry point — lazily initializes the correct client and routes all `complete()` calls.
118 
119### Model Resolution
120 
121`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.
122 
123### Session Monitoring Pipeline
124 
125```
126CLI agent writes JSONL/DB files
127  → SessionProvider (normalizes to ClaudeSessionEvent)
128    → SessionMonitor (watches files, aggregates stats, emits events)
129      → Dashboard / MindMap / KanbanBoard / TreeViews / Notifications
130```
131 
132Provider implementations live in `src/services/providers/`. Each normalizes raw data into `ClaudeSessionEvent` format defined in `src/types/claudeSession.ts`.
133 
134### Request Management
135 
136- **Debouncing**: Configurable delay (default 1000ms) before firing inline completion requests
137- **LRU cache**: `CompletionCache` — 100 entries, 30s TTL
138- **Cancellation**: `AbortController` linked through `CompletionOptions.signal`
139- **Timeouts**: `TimeoutManager` provides per-operation timeouts with context-size scaling
140 
141### Key Source Locations
142 
143- **Entry point**: `src/extension.ts` — `activate()`, all command/provider registration
144- **Core types**: `src/types.ts` (ClaudeClient, CompletionOptions), `src/types/` (per-feature types)
145- **Prompt templates**: `src/utils/prompts.ts`, `src/utils/analysisPrompts.ts`, `src/utils/summaryPrompts.ts`
146- **Inference clients**: `src/services/AuthService.ts`, `MaxSubscriptionClient.ts`, `ApiKeyClient.ts`, `OpenCodeClient.ts`, `CodexClient.ts` (spawns CLI directly, no SDK)
147- **Session providers**: `src/services/providers/ClaudeCodeSessionProvider.ts`, `OpenCodeSessionProvider.ts`, `CodexSessionProvider.ts`
148- **z.ai quota** (shared): `sidekick-shared/src/zaiQuotaApi.ts` — `resolveZaiQuota()` reads z.ai's authoritative `api/monitor/usage/quota/limit` endpoint (5-Hour / Weekly windows), discovering credentials from OpenCode's stored z.ai token (`zai-coding-plan` → `zai`) or `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`, with cached-snapshot fallback. The older observed-traffic estimator (`zaiQuota.ts` / `zaiQuotaWatcher.ts`) is retained for backward compatibility but deprecated and no longer used for product quota display. z.ai is monitored-only — no z.ai inference provider or account-management surface yet
149- **Webview UI**: `src/webview/` — vanilla TS bundled as IIFE; Chart.js and D3.js load from local vendor bundles
150 
151### Persistence
152 
153Cross-session data stored in `~/.config/sidekick/`:
154 
155- `historical-data.json` — token/cost/tool usage stats
156- `tasks/{projectSlug}.json` — kanban board carry-over
157- `decisions/{projectSlug}.json` — decision log
158 
159## Sidekick CLI and Shared Library
160 
161The CLI reads from `~/.config/sidekick/` (same data as the VS Code extension). Build everything with `bash scripts/build-all.sh`. Shared data access lives in `sidekick-shared/` (tsc-built TypeScript library); the terminal dashboard lives in `sidekick-cli/` (esbuild-bundled ESM binary).
162 
163- **npm package**: `sidekick-agent-hub` — the **binary name** is `sidekick` (defined in `sidekick-cli/package.json` `bin` field), not `sidekick-agent-hub`
164- **shared npm package**: `sidekick-shared` — published independently for consumers that need readers, providers, schemas, formatting, model info, and session asset extraction
165- **CLI discovery**: `SidekickCliService.ts` searches configured path → common paths (including nvm) → `which sidekick`
166- **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.
167 
168## Testing
169 
170Tests 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.
171 
172## Conventions
173 
174- **TypeScript**: `strict: true`, target ES2022. The extension uses `noEmit: true` and builds with esbuild; `sidekick-shared` emits declarations and JavaScript via `tsc`.
175- **Linting**: ESLint 9 + typescript-eslint; `@typescript-eslint/no-explicit-any` is `warn`; unused vars prefixed with `_` are allowed
176- **Commits**: Conventional Commits (`feat(scope):`, `fix(scope):`, etc.)
177- **Branches**: `feature/`, `fix/`, `docs/`, `refactor/` prefixes
178- **File naming**: PascalCase for classes/services, camelCase for utilities
179- **Settings prefix**: All VS Code settings use `sidekick.*`
180 
181## Release Process
182 
183Releases are triggered by pushing a `v*` tag to `main`. The CI workflow (`.github/workflows/release.yml`) runs five jobs:
184 
1851. **Validate Version** — verifies tag is on `main` and all three `package.json` versions match the tag
1862. **Publish VS Code Extension** — lint, test, package `.vsix`, upload as artifact, publish to Open VSX
1873. **Publish Shared Library to npm** — lint, test, build, publish `sidekick-shared` (skips if version already published)
1884. **Publish CLI to npm** — build shared lib, test CLI, build CLI, verify binary, publish `sidekick-agent-hub` (skips if version already published)
1895. **Create GitHub Release** — downloads `.vsix` artifact, extracts changelog section, creates release with `.vsix` attached
190 
191**Version bump checklist** (all must match the tag):
192 
193- `bash scripts/bump-version.sh <version>` bumps the three `package.json` files at once. It does **not** touch lockfiles, so still:
194  - `sidekick-vscode/package-lock.json`, `sidekick-cli/package-lock.json`, and `sidekick-shared/package-lock.json` (run `npm install --package-lock-only` in each workspace)
195- If bumping by hand instead, the three `package.json` files are: `sidekick-vscode/`, `sidekick-cli/`, `sidekick-shared/`
196 
197**Changelogs to update** (five total):
198 
199- `CHANGELOG.md` (root — full project)
200- `sidekick-vscode/CHANGELOG.md` (extension-specific)
201- `sidekick-cli/CHANGELOG.md` (CLI-specific)
202- `sidekick-shared/CHANGELOG.md` (shared-library-specific)
203- `docs/changelog.md` (documentation site)
204