| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 12 | 0% |
| Commands | 4 | 2 | 5 | 36% |
| Section tags | 4 | 3 | 4 | 36% |
What each file covers
Sections
0 shared · 6 only in A · 12 only in B- − AGENTS.md
- − Workflow
- − Coding Standards
- − Adding a New Tool — Checklist
- − Dependencies
- − Anti-Patterns to Avoid
- + CLAUDE.md
- + What This Project Is
- + Build & Development Commands
- + Architecture
- + Core Flow
- + Types
- + Adding a New Platform
- + Testing
- + Test-Driven Development
- + Test file conventions
- + Minimum test coverage for PRs
- + Key Conventions
Commands
4 shared · 2 only in A · 5 only in B- − pnpm run check
- − pnpm lint && pnpm build
- + pnpm install
- + pnpm run build
- + pnpm run dev
- + npx vitest run src/__tests__/unit-conversions.test.ts
- + vitest.config.ts
- pnpm test
- pnpm run link
- pnpm run test:watch
- node:sqlite
Section tags
4 shared · 3 only in A · 4 only in B- − lint-format
- − dependencies
- − do-not
- + setup
- + build
- + types
- + git-pr
- test
- code-style
- testing-strategy
- agent-behaviour
Line diff
yigitkonur/cli-continues · AGENTS.md
@@ −1 @@
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
yigitkonur/cli-continues · CLAUDE.md
@@ +1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## What This Project Is
6
7`continues` is a CLI tool that lets users resume AI coding sessions across Claude Code, GitHub Copilot CLI, Gemini CLI, Codex CLI, OpenCode, Factory Droid, and Cursor AI. It reads each tool's native session storage (read-only), extracts context (messages, file changes, tool activity, AI reasoning), and injects it into a different tool as a structured markdown handoff document.
8
9## Build & Development Commands
10
11```bash
12pnpm install # Install dependencies
13pnpm run build # TypeScript compile (tsc) → dist/
14pnpm run dev # Run with tsx (no build step)
15pnpm test # Run unit tests (vitest)
16pnpm run test:watch # Watch mode
17pnpm run link # Build + pnpm link --global (local testing as `continues` / `cont`)
18```
19
20Run a single test file:
21```bash
22npx vitest run src/__tests__/unit-conversions.test.ts
23```
24
25Requires **Node.js 22+** (uses built-in `node:sqlite` for OpenCode parsing).
26
27## Architecture
28
29### Core Flow
30
31```
32CLI (src/cli.ts) → Registry (src/parsers/registry.ts) → Index (src/utils/index.ts) → Parsers (src/parsers/*.ts) → Markdown (src/utils/markdown.ts) → Resume (src/utils/resume.ts)
33```
34
351. **Adapter Registry** (`src/parsers/registry.ts`): Central `ToolAdapter` interface and `adapters` record. Every supported CLI tool is registered here with its parser functions, resume commands, color, label, and storage path. All other modules derive their behavior from the registry — no manual switch statements or hardcoded tool lists.
36
372. **CLI** (`src/cli.ts`): Commander-based CLI with interactive TUI (@clack/prompts). Handles `list`, `resume`, `scan`, `rebuild`, `pick`, and per-tool quick-resume subcommands. Quick-resume commands and source colors are generated from the registry automatically.
38
393. **Session Index** (`src/utils/index.ts`): Builds and caches a unified JSONL index at `~/.continues/sessions.jsonl` (5-min TTL). Calls all parsers in parallel via `Promise.allSettled` (one broken parser won't crash the CLI), merges and sorts by `updatedAt`.
40
414. **Parsers** (`src/parsers/*.ts`): One file per tool. Each exports `parse<Tool>Sessions()` (discovery + metadata) and `extract<Tool>Context()` (full conversation + tool activity extraction). Formats vary:
42 - `claude.ts` — JSONL files under `~/.claude/projects/`, streamed with `readline`
43 - `codex.ts` — JSONL files under `~/.codex/sessions/`, streamed with `readline`
44 - `copilot.ts` — YAML workspace + JSONL events under `~/.copilot/session-state/`
45 - `gemini.ts` — JSON files under `~/.gemini/tmp/*/chats/`
46 - `opencode.ts` — SQLite DB at `~/.local/share/opencode/opencode.db` (via `node:sqlite`), with JSON file fallback
47 - `droid.ts` — JSONL + companion `.settings.json` under `~/.factory/sessions/<workspace-slug>/`
48 - `cursor.ts` — JSONL agent transcripts under `~/.cursor/projects/*/agent-transcripts/`
49
505. **Shared Utilities** (`src/utils/parser-helpers.ts`): Common functions shared by parsers — `cleanSummary()`, `extractRepoFromCwd()`, `homeDir()`.
51
526. **Tool Summarizer** (`src/utils/tool-summarizer.ts`): `SummaryCollector` class + formatting helpers (`shellSummary`, `fileSummary`, `grepSummary`, etc.) shared by all parsers to produce consistent one-line tool activity summaries.
53
547. **Markdown Generator** (`src/utils/markdown.ts`): `generateHandoffMarkdown()` takes parsed session data and produces the structured handoff document with overview table, tool activity, key decisions, recent conversation, files modified, and pending tasks.
55
568. **Resume** (`src/utils/resume.ts`): Handles both native resume (same tool) and cross-tool handoff. Uses the adapter registry for CLI binary names and argument patterns. For cross-tool: extracts context, saves `.continues-handoff.md` to project dir, then spawns the target CLI with the inline or reference prompt.
57
58### Types
59
60`src/types/index.ts` defines: `SessionSource` (union of 7 tool names), `UnifiedSession`, `ConversationMessage`, `ToolCall`, `ToolUsageSummary`, `SessionNotes`, `SessionContext`, `HandoffOptions`.
61
62### Adding a New Platform
63
64Adding support for a new AI coding CLI (e.g. "newtool") requires changes in **3 files**. Use `codex.ts` as the simplest reference parser.
65
66#### 1. Add to the `SessionSource` type — `src/types/index.ts`
67
68Add the new tool name to the union type:
69```ts
70export type SessionSource = 'codex' | 'claude' | 'copilot' | 'gemini' | 'opencode' | 'droid' | 'cursor' | 'newtool';
71```
72
73#### 2. Create the parser — `src/parsers/newtool.ts`
74
75Export two functions following the established pattern:
76
77- `parseNewtoolSessions(): Promise<UnifiedSession[]>` — Discovers session files from the tool's storage directory, reads metadata (id, cwd, repo, branch, timestamps, summary), and returns `UnifiedSession[]` sorted by `updatedAt` descending.
78- `extractNewtoolContext(session: UnifiedSession): Promise<SessionContext>` — Reads the full session, extracts `ConversationMessage[]`, uses `SummaryCollector` from `tool-summarizer.ts` to collect tool activity, and calls `generateHandoffMarkdown()` from `utils/markdown.ts` to produce the final markdown. Returns a `SessionContext`.
79
80Key patterns from existing parsers:
81- Import shared utilities: `import { cleanSummary, extractRepoFromCwd, homeDir } from '../utils/parser-helpers.js';`
82- Session discovery: walk the tool's storage directory, filter by file extension/naming pattern.
83- For JSONL formats: stream with `readline.createInterface` to avoid loading entire files into memory.
84- Use `SummaryCollector.add(category, summary, filePath?, isWrite?)` to accumulate tool usage and track modified files.
85- Keep only the last ~10 messages in `recentMessages` for the handoff, but ensure at least one user message is included.
86- Silently skip files/sessions that fail to parse (`catch {}` blocks).
87
88#### 3. Register in the adapter registry — `src/parsers/registry.ts`
89
90Add an entry to the registry with all metadata, parser functions, and resume commands:
91```ts
92import { parseNewtoolSessions, extractNewtoolContext } from './newtool.js';
93
94register({
95 name: 'newtool',
96 label: 'NewTool',
97 color: chalk.hex('#FF6600'),
98 storagePath: '~/.newtool/sessions/',
99 binaryName: 'newtool',
100 parseSessions: parseNewtoolSessions,
101 extractContext: extractNewtoolContext,
102 nativeResumeArgs: (s) => ['--resume', s.id],
103 crossToolArgs: (prompt) => [prompt],
104 resumeCommandDisplay: (s) => `newtool --resume ${s.id}`,
105});
106```
107
108That's it — the registry automatically wires the new tool into the CLI (quick-resume commands, source colors, help text, session index, resume logic). No switch statements or hardcoded arrays to update.
109
110#### 4. Add test fixtures — `src/__tests__/fixtures/index.ts`
111
112Create a `createNewtoolFixture(): FixtureDir` function that:
113- Creates a temp directory matching the tool's storage layout.
114- Writes minimal but realistic session data (at least 2 user messages + 2 assistant messages).
115- Returns `{ root, cleanup }`.
116
117Then add conversion test cases in `src/__tests__/unit-conversions.test.ts` covering the new tool as both source and target (N-1 new conversion paths for each direction).
118
119## Testing
120
121Tests live in `src/__tests__/`. The vitest config (`vitest.config.ts`) **excludes** several test files by pattern: `e2e*`, `real-e2e*`, `stress*`, `injection*`, `parsers.test*`, `conversions.test*` (legacy file; the active suite is `unit-conversions.test.ts`). The primary test suite is `unit-conversions.test.ts`, which uses fixture data from `src/__tests__/fixtures/index.ts` to test all 42 cross-tool conversion paths (7 tools × 6 targets each) without requiring real session files on the machine.
122
123## Test-Driven Development
124
125Every code change should follow TDD discipline:
126
1271. **Write the test first** — parser changes, new features, and bug fixes all start with a failing test.
1282. **Ground fixtures in real schemas** — before creating fixture data, read a real session file to verify field names and data structure. Use the Read tool or MCP to inspect the actual storage paths (`~/.claude/projects/`, `~/.codex/sessions/`, `~/.copilot/session-state/`, `~/.gemini/tmp/*/chats/`, `~/.local/share/opencode/`, `~/.factory/sessions/`, `~/.cursor/projects/*/agent-transcripts/`).
1293. **If real session data isn't available** — ask the user to provide a sample or point to the storage directory. Don't invent schemas from imagination.
130
131### Test file conventions
132
133- **Parser/conversion tests**: `src/__tests__/unit-conversions.test.ts` — the primary test suite (fixture-based, all conversion paths)
134- **Utility tests**: dedicated files (e.g. `src/__tests__/cwd-matching.test.ts`)
135- **Fixtures**: `src/__tests__/fixtures/index.ts` — one `createXxxFixture()` factory per tool
136
137### Minimum test coverage for PRs
138
139- **New parser**: fixture factory + low-level parsing tests + all N-1 conversion paths in each direction
140- **New utility function**: dedicated test file with edge cases
141- **Bug fix**: regression test that reproduces the bug before the fix is applied
142
143## Key Conventions
144
145- ESM-only (`"type": "module"` in package.json). All local imports use `.js` extensions.
146- `process.exitCode` is set instead of calling `process.exit()` directly.
147- The tool suppresses `ExperimentalWarning` from `node:sqlite` at the top of `cli.ts`.
148- Session data is **read-only** — the tool never modifies source session files.
149- The index cache and handoff contexts are stored under `~/.continues/`.
150
@@ −1 +1 @@
1−# AGENTS.md
1+# CLAUDE.md
22
3−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.
3+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44
5−## Workflow
5+## What This Project Is
66
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.
7+`continues` is a CLI tool that lets users resume AI coding sessions across Claude Code, GitHub Copilot CLI, Gemini CLI, Codex CLI, OpenCode, Factory Droid, and Cursor AI. It reads each tool's native session storage (read-only), extracts context (messages, file changes, tool activity, AI reasoning), and injects it into a different tool as a structured markdown handoff document.
118
12−## Coding Standards
9+## Build & Development Commands
1310
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.
11+```bash
12+pnpm install # Install dependencies
13+pnpm run build # TypeScript compile (tsc) → dist/
14+pnpm run dev # Run with tsx (no build step)
15+pnpm test # Run unit tests (vitest)
16+pnpm run test:watch # Watch mode
17+pnpm run link # Build + pnpm link --global (local testing as `continues` / `cont`)
18+```
2319
24−## Adding a New Tool — Checklist
20+Run a single test file:
21+```bash
22+npx vitest run src/__tests__/unit-conversions.test.ts
23+```
2524
26−All five steps are required. Missing any one is a bug. See `CLAUDE.md` for detailed implementation guidance.
25+Requires **Node.js 22+** (uses built-in `node:sqlite` for OpenCode parsing).
2726
28−1. Add tool name to `TOOL_NAMES` in `src/types/tool-names.ts`
29−2. Create `src/parsers/<tool>.ts` exporting `parse<Tool>Sessions()` and `extract<Tool>Context()`
30−3. Register in `src/parsers/registry.ts` (the completeness assertion throws at module load if missing)
31−4. Add `create<Tool>Fixture()` in `src/__tests__/fixtures/index.ts`
32−5. Add conversion test cases in `src/__tests__/unit-conversions.test.ts`
27+## Architecture
3328
34−## Dependencies
29+### Core Flow
3530
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.
31+```
32+CLI (src/cli.ts) → Registry (src/parsers/registry.ts) → Index (src/utils/index.ts) → Parsers (src/parsers/*.ts) → Markdown (src/utils/markdown.ts) → Resume (src/utils/resume.ts)
33+```
4334
44−## Anti-Patterns to Avoid
35+1. **Adapter Registry** (`src/parsers/registry.ts`): Central `ToolAdapter` interface and `adapters` record. Every supported CLI tool is registered here with its parser functions, resume commands, color, label, and storage path. All other modules derive their behavior from the registry — no manual switch statements or hardcoded tool lists.
4536
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.
37+2. **CLI** (`src/cli.ts`): Commander-based CLI with interactive TUI (@clack/prompts). Handles `list`, `resume`, `scan`, `rebuild`, `pick`, and per-tool quick-resume subcommands. Quick-resume commands and source colors are generated from the registry automatically.
38+
39+3. **Session Index** (`src/utils/index.ts`): Builds and caches a unified JSONL index at `~/.continues/sessions.jsonl` (5-min TTL). Calls all parsers in parallel via `Promise.allSettled` (one broken parser won't crash the CLI), merges and sorts by `updatedAt`.
40+
41+4. **Parsers** (`src/parsers/*.ts`): One file per tool. Each exports `parse<Tool>Sessions()` (discovery + metadata) and `extract<Tool>Context()` (full conversation + tool activity extraction). Formats vary:
42+ - `claude.ts` — JSONL files under `~/.claude/projects/`, streamed with `readline`
43+ - `codex.ts` — JSONL files under `~/.codex/sessions/`, streamed with `readline`
44+ - `copilot.ts` — YAML workspace + JSONL events under `~/.copilot/session-state/`
45+ - `gemini.ts` — JSON files under `~/.gemini/tmp/*/chats/`
46+ - `opencode.ts` — SQLite DB at `~/.local/share/opencode/opencode.db` (via `node:sqlite`), with JSON file fallback
47+ - `droid.ts` — JSONL + companion `.settings.json` under `~/.factory/sessions/<workspace-slug>/`
48+ - `cursor.ts` — JSONL agent transcripts under `~/.cursor/projects/*/agent-transcripts/`
49+
50+5. **Shared Utilities** (`src/utils/parser-helpers.ts`): Common functions shared by parsers — `cleanSummary()`, `extractRepoFromCwd()`, `homeDir()`.
51+
52+6. **Tool Summarizer** (`src/utils/tool-summarizer.ts`): `SummaryCollector` class + formatting helpers (`shellSummary`, `fileSummary`, `grepSummary`, etc.) shared by all parsers to produce consistent one-line tool activity summaries.
53+
54+7. **Markdown Generator** (`src/utils/markdown.ts`): `generateHandoffMarkdown()` takes parsed session data and produces the structured handoff document with overview table, tool activity, key decisions, recent conversation, files modified, and pending tasks.
55+
56+8. **Resume** (`src/utils/resume.ts`): Handles both native resume (same tool) and cross-tool handoff. Uses the adapter registry for CLI binary names and argument patterns. For cross-tool: extracts context, saves `.continues-handoff.md` to project dir, then spawns the target CLI with the inline or reference prompt.
57+
58+### Types
59+
60+`src/types/index.ts` defines: `SessionSource` (union of 7 tool names), `UnifiedSession`, `ConversationMessage`, `ToolCall`, `ToolUsageSummary`, `SessionNotes`, `SessionContext`, `HandoffOptions`.
61+
62+### Adding a New Platform
63+
64+Adding support for a new AI coding CLI (e.g. "newtool") requires changes in **3 files**. Use `codex.ts` as the simplest reference parser.
65+
66+#### 1. Add to the `SessionSource` type — `src/types/index.ts`
67+
68+Add the new tool name to the union type:
69+```ts
70+export type SessionSource = 'codex' | 'claude' | 'copilot' | 'gemini' | 'opencode' | 'droid' | 'cursor' | 'newtool';
71+```
72+
73+#### 2. Create the parser — `src/parsers/newtool.ts`
74+
75+Export two functions following the established pattern:
76+
77+- `parseNewtoolSessions(): Promise<UnifiedSession[]>` — Discovers session files from the tool's storage directory, reads metadata (id, cwd, repo, branch, timestamps, summary), and returns `UnifiedSession[]` sorted by `updatedAt` descending.
78+- `extractNewtoolContext(session: UnifiedSession): Promise<SessionContext>` — Reads the full session, extracts `ConversationMessage[]`, uses `SummaryCollector` from `tool-summarizer.ts` to collect tool activity, and calls `generateHandoffMarkdown()` from `utils/markdown.ts` to produce the final markdown. Returns a `SessionContext`.
79+
80+Key patterns from existing parsers:
81+- Import shared utilities: `import { cleanSummary, extractRepoFromCwd, homeDir } from '../utils/parser-helpers.js';`
82+- Session discovery: walk the tool's storage directory, filter by file extension/naming pattern.
83+- For JSONL formats: stream with `readline.createInterface` to avoid loading entire files into memory.
84+- Use `SummaryCollector.add(category, summary, filePath?, isWrite?)` to accumulate tool usage and track modified files.
85+- Keep only the last ~10 messages in `recentMessages` for the handoff, but ensure at least one user message is included.
86+- Silently skip files/sessions that fail to parse (`catch {}` blocks).
87+
88+#### 3. Register in the adapter registry — `src/parsers/registry.ts`
89+
90+Add an entry to the registry with all metadata, parser functions, and resume commands:
91+```ts
92+import { parseNewtoolSessions, extractNewtoolContext } from './newtool.js';
93+
94+register({
95+ name: 'newtool',
96+ label: 'NewTool',
97+ color: chalk.hex('#FF6600'),
98+ storagePath: '~/.newtool/sessions/',
99+ binaryName: 'newtool',
100+ parseSessions: parseNewtoolSessions,
101+ extractContext: extractNewtoolContext,
102+ nativeResumeArgs: (s) => ['--resume', s.id],
103+ crossToolArgs: (prompt) => [prompt],
104+ resumeCommandDisplay: (s) => `newtool --resume ${s.id}`,
105+});
106+```
107+
108+That's it — the registry automatically wires the new tool into the CLI (quick-resume commands, source colors, help text, session index, resume logic). No switch statements or hardcoded arrays to update.
109+
110+#### 4. Add test fixtures — `src/__tests__/fixtures/index.ts`
111+
112+Create a `createNewtoolFixture(): FixtureDir` function that:
113+- Creates a temp directory matching the tool's storage layout.
114+- Writes minimal but realistic session data (at least 2 user messages + 2 assistant messages).
115+- Returns `{ root, cleanup }`.
116+
117+Then add conversion test cases in `src/__tests__/unit-conversions.test.ts` covering the new tool as both source and target (N-1 new conversion paths for each direction).
118+
119+## Testing
120+
121+Tests live in `src/__tests__/`. The vitest config (`vitest.config.ts`) **excludes** several test files by pattern: `e2e*`, `real-e2e*`, `stress*`, `injection*`, `parsers.test*`, `conversions.test*` (legacy file; the active suite is `unit-conversions.test.ts`). The primary test suite is `unit-conversions.test.ts`, which uses fixture data from `src/__tests__/fixtures/index.ts` to test all 42 cross-tool conversion paths (7 tools × 6 targets each) without requiring real session files on the machine.
122+
123+## Test-Driven Development
124+
125+Every code change should follow TDD discipline:
126+
127+1. **Write the test first** — parser changes, new features, and bug fixes all start with a failing test.
128+2. **Ground fixtures in real schemas** — before creating fixture data, read a real session file to verify field names and data structure. Use the Read tool or MCP to inspect the actual storage paths (`~/.claude/projects/`, `~/.codex/sessions/`, `~/.copilot/session-state/`, `~/.gemini/tmp/*/chats/`, `~/.local/share/opencode/`, `~/.factory/sessions/`, `~/.cursor/projects/*/agent-transcripts/`).
129+3. **If real session data isn't available** — ask the user to provide a sample or point to the storage directory. Don't invent schemas from imagination.
130+
131+### Test file conventions
132+
133+- **Parser/conversion tests**: `src/__tests__/unit-conversions.test.ts` — the primary test suite (fixture-based, all conversion paths)
134+- **Utility tests**: dedicated files (e.g. `src/__tests__/cwd-matching.test.ts`)
135+- **Fixtures**: `src/__tests__/fixtures/index.ts` — one `createXxxFixture()` factory per tool
136+
137+### Minimum test coverage for PRs
138+
139+- **New parser**: fixture factory + low-level parsing tests + all N-1 conversion paths in each direction
140+- **New utility function**: dedicated test file with edge cases
141+- **Bug fix**: regression test that reproduces the bug before the fix is applied
142+
143+## Key Conventions
144+
145+- ESM-only (`"type": "module"` in package.json). All local imports use `.js` extensions.
146+- `process.exitCode` is set instead of calling `process.exit()` directly.
147+- The tool suppresses `ExperimentalWarning` from `node:sqlite` at the top of `cli.ts`.
148+- Session data is **read-only** — the tool never modifies source session files.
149+- The index cache and handoff contexts are stored under `~/.continues/`.
53150
