Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (40 loc) · 4.09 KB

AGENTS.md

File metadata and controls

52 lines (40 loc) · 4.09 KB

AGENTS.md

Agent 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.

Workflow

  • Before any commit: run pnpm run check (pnpm lint && pnpm build). Fix all Biome errors; warnings are advisory.
  • After changing a parser or fixture: run pnpm test and confirm all tests pass. Do not commit with failing tests.
  • After adding a new tool: run pnpm run link to test the global continues / cont binary locally.
  • 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.

Coding Standards

  • ESM-only: all local imports must end in .js, even for .ts source files (e.g., import { foo } from './foo.js').
  • No any: Biome reports noExplicitAny as a warning. Avoid it; document the reason if unavoidable.
  • Exit codes: set process.exitCode = N rather than calling process.exit(N).
  • 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.
  • Error types: throw typed errors from src/errors.ts on user-facing paths, not bare new Error().
  • Tool activity: use SummaryCollector from src/utils/tool-summarizer.ts in every parser. Do not build ToolUsageSummary[] arrays manually.
  • JSONL: stream with readline.createInterface, never fs.readFileSync + split('\n').
  • SQLite (OpenCode, Crush parsers): use built-in node:sqlite — do not add third-party SQLite dependencies.
  • Biome rules in force: noEmptyBlockStatements (error), noUnusedImports (error), useConst (error). Empty catch {} blocks fail the linter; use catch (err) { logger.debug(...) } instead.

Adding a New Tool — Checklist

All five steps are required. Missing any one is a bug. See CLAUDE.md for detailed implementation guidance.

  1. Add tool name to TOOL_NAMES in src/types/tool-names.ts
  2. Create src/parsers/<tool>.ts exporting parse<Tool>Sessions() and extract<Tool>Context()
  3. Register in src/parsers/registry.ts (the completeness assertion throws at module load if missing)
  4. Add create<Tool>Fixture() in src/__tests__/fixtures/index.ts
  5. Add conversion test cases in src/__tests__/unit-conversions.test.ts

Dependencies

  • @clack/prompts — all interactive TUI prompts and spinners. Do not use readline or inquirer.
  • chalk — terminal color. Chalk v4 is installed (CommonJS compat import); do not upgrade to v5+ (ESM-only).
  • commander — CLI argument parsing.
  • ora — non-interactive spinners.
  • yaml — YAML parsing for Copilot sessions.
  • zod — runtime schema validation. Use z.safeParse() where failures are recoverable.
  • Do not add new runtime dependencies without strong justification. The install footprint is intentionally small.

Anti-Patterns to Avoid

  • Writing to tool storage directories — the tool is read-only. Any write to ~/.claude/, ~/.codex/, etc. is a severe bug.
  • exec() with string interpolation — always use spawn() with an argument array in resume.ts. Session IDs and paths can contain shell metacharacters.
  • fs.readFileSync/fs.writeFileSync in parsers — these block the event loop. Use async fs APIs or readline.
  • Duplicating parser-helpers — cleanSummary, extractRepoFromCwd, homeDir live in src/utils/parser-helpers.ts. Import them; do not reimplement.
  • Hardcoding tool names — derive from TOOL_NAMES or SessionSource. Never write if (tool === 'claude' || tool === 'codex' || ...).
  • Importing node:sqlite outside OpenCode/Crush parsers — SQLite is only needed for those two tools. Do not spread this dependency.
  • Embedding secrets in handoff markdown — .continues-handoff.md is written to project directories and may be committed or read by other AI tools.