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.2 KiB

Raw Blame History

Pi

Pi agent CLI.

Source: src/providers/pi.ts
Loading: eager (src/providers/index.ts:9)
Test: tests/providers/pi.test.ts (336 lines)

Where it reads from

~/.pi/agent/sessions/ (pi.ts:55-57).

Storage format

JSONL (pi.ts:98).

Caching

None.

Deduplication

Per <provider>:<path>:<responseId> when a response ID is present, falling back to the entry timestamp, and finally to a line index (pi.ts:164).

Quirks

Undefined token fields in message.usage are coerced to 0 (pi.ts:156-159); never undefined.
The provider name is taken from source.provider (pi.ts:182), not hard-coded. This matters because pi.ts is the parser for both Pi and OMP; see omp.md.
Tool-call content type is extracted from the message envelope (pi.ts:169-176).

When fixing a bug here

If you change parsing logic, also run tests/providers/omp.test.ts because OMP shares this code.
If the bug is "tokens are NaN", look at the coercion at pi.ts:156-159. A regression on this is silent and easy to miss.
If the bug is specific to the dedup behavior, decide which of the three fallback keys was used by adding a temporary log; the keys collide differently for old vs. new Pi versions.

1.2 KiB Raw Blame History

Pi