AGENTS.md

1# AGENTS.md
2 
3Agent behavior instructions for `continues` — the cross-tool AI session handoff CLI. Read `CLAUDE.md` for architecture, types, and the step-by-step guide for adding a new parser. This file covers workflow, coding standards, and anti-patterns.
4 
5## Workflow
6 
7- **Before any commit**: run `pnpm run check` (`pnpm lint && pnpm build`). Fix all Biome errors; warnings are advisory.
8- **After changing a parser or fixture**: run `pnpm test` and confirm all tests pass. Do not commit with failing tests.
9- **After adding a new tool**: run `pnpm run link` to test the global `continues` / `cont` binary locally.
10- **Never run** `pnpm run test:watch`, `e2e-conversions.test.ts`, `real-e2e-full.ts`, or `stress-test.ts` in CI — these require live session files on the developer's machine.
11 
12## Coding Standards
13 
14- **ESM-only**: all local imports must end in `.js`, even for `.ts` source files (e.g., `import { foo } from './foo.js'`).
15- **No `any`**: Biome reports `noExplicitAny` as a warning. Avoid it; document the reason if unavoidable.
16- **Exit codes**: set `process.exitCode = N` rather than calling `process.exit(N)`.
17- **Logging**: use `logger` from `src/logger.ts` for all diagnostic output. Never use bare `console.log`/`console.warn`/`console.error` in library code. TUI display goes through `@clack/prompts` or `chalk` via the display layer.
18- **Error types**: throw typed errors from `src/errors.ts` on user-facing paths, not bare `new Error()`.
19- **Tool activity**: use `SummaryCollector` from `src/utils/tool-summarizer.ts` in every parser. Do not build `ToolUsageSummary[]` arrays manually.
20- **JSONL**: use the shared streaming helpers in `src/utils/jsonl.ts`, never `fs.readFileSync` + `split('\n')`.
21- **SQLite** (OpenCode, Crush parsers): use built-in `node:sqlite` — do not add third-party SQLite dependencies.
22- **Biome rules in force**: `noEmptyBlockStatements` (error), `noUnusedImports` (error), `useConst` (error). Empty `catch {}` blocks fail the linter; use `catch (err) { logger.debug(...) }` instead.
23 
24## Adding a New Tool — Checklist
25 
26All five steps are required. Missing any one is a bug. See `CLAUDE.md` for detailed implementation guidance.
27 
281. Add tool name to `TOOL_NAMES` in `src/types/tool-names.ts`
292. Create `src/parsers/<tool>.ts` exporting `parse<Tool>Sessions()` and `extract<Tool>Context()`
303. Register in `src/parsers/registry.ts` (the completeness assertion throws at module load if missing)
314. Add `create<Tool>Fixture()` in `src/__tests__/fixtures/index.ts`
325. Add conversion test cases in `src/__tests__/unit-conversions.test.ts`
33 
34## Dependencies
35 
36- **`@clack/prompts`** — all interactive TUI prompts and spinners. Do not use `readline` or `inquirer`.
37- **`chalk`** — terminal color. Chalk v4 is installed (CommonJS compat import); do not upgrade to v5+ (ESM-only).
38- **`commander`** — CLI argument parsing.
39- **`ora`** — non-interactive spinners.
40- **`yaml`** — YAML parsing for Copilot sessions.
41- **`zod`** — runtime schema validation. Use `z.safeParse()` where failures are recoverable.
42- Do not add new runtime dependencies without strong justification. The install footprint is intentionally small.
43 
44## Anti-Patterns to Avoid
45 
46- **Writing to tool storage directories** — the tool is read-only. Any write to `~/.claude/`, `~/.codex/`, etc. is a severe bug.
47- **`exec()` with string interpolation** — always use `spawn()` with an argument array in `resume.ts`. Session IDs and paths can contain shell metacharacters.
48- **`fs.readFileSync`/`fs.writeFileSync` in parsers** — these block the event loop. Use async fs APIs or shared streaming helpers.
49- **Duplicating parser-helpers** — `cleanSummary`, `extractRepoFromCwd`, `homeDir` live in `src/utils/parser-helpers.ts`. Import them; do not reimplement.
50- **Hardcoding tool names** — derive from `TOOL_NAMES` or `SessionSource`. Never write `if (tool === 'claude' || tool === 'codex' || ...)`.
51- **Importing `node:sqlite` outside OpenCode/Crush parsers** — SQLite is only needed for those two tools. Do not spread this dependency.
52- **Embedding secrets in handoff markdown** — `.continues-handoff.md` is written to project directories and may be committed or read by other AI tools.
53