6746ecc22f
Document the contributor onboarding path: - CONTRIBUTING.md: setup, npm scripts, coding conventions, PR process, the block-claude-coauthor enforcement, and the five providers without test coverage today (claude, gemini, goose, qwen, antigravity). - docs/architecture.md: 12-command CLI surface, parser pipeline, three cache layers, 14 optimize detectors, and the mac / gnome / build layouts with cited line numbers. - docs/providers/: one file per provider (17 providers plus the shared vscode-cline-parser helper). Each covers data path, storage format, caching, dedup key, quirks, and a "when fixing a bug here" checklist. Also fix two pre-existing documentation issues surfaced while writing the new docs: - RELEASING.md claimed GitHub Actions auto-publishes the CLI when a v* tag is pushed. There is no such workflow; CLI publishing is manual via npm publish. Updated the CLI section to reflect reality and kept the menubar (mac-v* tag) automation accurate. - .gitignore had CLAUDE.md unanchored, which on case-insensitive filesystems also matched docs/providers/claude.md. Anchored to /CLAUDE.md so the root-level memory file stays ignored without affecting subdirectory docs. All cited file paths, line numbers, function names, and test counts were verified against current code (41 test files, 558 tests passing).
2.7 KiB
vscode-cline-parser (Shared Helper)
Shared discovery and parsing for VS Code extensions descended from Cline.
- Source:
src/providers/vscode-cline-parser.ts - Loading: not a provider; imported by
kilo-code.tsandroo-code.ts. - Test: none directly. Coverage comes from
tests/providers/kilo-code.test.tsandtests/providers/roo-code.test.ts.
What it does
Two responsibilities:
discoverClineTasks(extensionId)walks VS Code'sglobalStorage/<extensionId>/tasks/directories and returns one source per task that has aui_messages.jsonfile (vscode-cline-parser.ts:25-50).createClineParserreads each task'sui_messages.jsonandapi_conversation_history.json, extracts model, tools, and token counts, and yieldsParsedProviderCallobjects.
Storage layout
Per task directory:
<globalStorage>/<extensionId>/tasks/<taskId>/
ui_messages.json # event stream
api_conversation_history.json # full prompt history with model tags
Model resolution
The model is extracted from api_conversation_history.json by searching user message content blocks for a <model>...</model> tag (vscode-cline-parser.ts:54-72). Falls back to cline-auto if no tag is found.
Token extraction
From api_req_started entries inside ui_messages.json. Each such entry's text field is JSON-parsed; the parsed object holds tokensIn, tokensOut, cacheReads, cacheWrites, and (optionally) cost (vscode-cline-parser.ts:119-134).
If cost is present, it is used directly. If not, calculateCost from src/models.ts computes it from tokens (vscode-cline-parser.ts:139).
Deduplication
Per <providerName>:<taskId>:<index> where index is the position of the api_req_started entry within ui_messages.json (vscode-cline-parser.ts:109).
Quirks
- Only the first user message is emitted as
userMessagein theParsedProviderCall(vscode-cline-parser.ts:157). Subsequent user turns are accounted but not surfaced. - The model regex looks inside content blocks, not at top-level fields. Some Cline-derivative extensions emit the model elsewhere; if you add support for one, branch on extension ID rather than rewriting the regex.
When fixing a bug here
- A change here ripples to both KiloCode and Roo Code. Run both test files (
tests/providers/kilo-code.test.tsandtests/providers/roo-code.test.ts) before opening a PR. - If you find that one of the two extensions emits a different shape, branch on the extension ID parameter that the discovery function already takes; do not duplicate the parser.
- If you add support for a third Cline-derivative extension, register it as a thin wrapper file in the same shape as
kilo-code.tsandroo-code.ts.