mirror of https://github.com/AgentSeal/codeburn.git synced 2026-05-17 03:56:45 +00:00

Add CONTRIBUTING.md, docs/architecture.md, and per-provider docs (#284 )

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

2026-05-09 18:39:41 -07:00

1.5 KiB

Raw Permalink Blame History

Gemini

Google Gemini CLI.

Source: src/providers/gemini.ts
Loading: eager (src/providers/index.ts:5)
Test: none. Adding a fixture-based test is a known good first issue.

Where it reads from

~/.gemini/tmp/<project>/chats/session-*.json and session-*.jsonl (gemini.ts:218-252).

Storage format

Either a single JSON document per session or JSONL, depending on Gemini CLI version. The parser sniffs the first non-whitespace character to decide (gemini.ts:197-206).

Caching

None.

Deduplication

Per sessionId (gemini.ts:72). Gemini sessions are aggregated to a single call per session.

Quirks

Cached tokens are a subset of input. Gemini reports cached tokens included inside promptTokenCount. The parser subtracts them so callers see Anthropic semantics (cached are separate).
Thoughts are billed at output rate (gemini.ts:125).
Each session collapses to one ParsedProviderCall. If you need per-turn data, the upstream format does not support it without re-parsing the prompt history.

When fixing a bug here

The lack of a test file is a hazard. Add a fixture and a test before changing parsing logic so future regressions are caught.
If the bug involves a new Gemini version's schema, sniff with the same first-character heuristic; do not call JSON.parse on the whole file.
If the bug is "Gemini sessions report less than expected", check whether the cached-token subtraction is over-correcting.

1.5 KiB Raw Permalink Blame History