mirror of https://github.com/AgentSeal/codeburn.git synced 2026-05-17 21:11:37 +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

2.4 KiB

Raw Permalink Blame History

Claude

Anthropic Claude Code CLI and Claude Desktop's local agent mode.

Source: src/providers/claude.ts
Loading: eager (src/providers/index.ts:1)
Test: none directly. Coverage comes from tests/parser-claude-cwd.test.ts, tests/parser-filter.test.ts, and tests/parser-mcp-inventory.test.ts, which exercise src/parser.ts end-to-end against fixture session files.

Where it reads from

Source	Path
Claude Code CLI	`$CLAUDE_CONFIG_DIR` if set, otherwise `~/.claude/projects/`
Claude Desktop (macOS)	`~/Library/Application Support/Claude/local-agent-mode-sessions/`
Claude Desktop (Windows)	`%APPDATA%/Claude/local-agent-mode-sessions/`
Claude Desktop (Linux)	`~/.config/Claude/local-agent-mode-sessions/`

For Desktop, findDesktopProjectDirs walks up to 8 levels deep looking for projects/ subdirectories, skipping node_modules and .git.

Storage format

JSONL, one event per line, per session file. Sessions live under <project>/<sessionId>.jsonl.

Parser

createSessionParser returns an empty async generator (claude.ts:101-105). Claude is a special case: src/parser.ts reads Claude JSONL files directly with full turn grouping, dedup of streaming message IDs, and MCP tool inventory extraction. The provider object exists only so discoverSessions can return Claude session sources alongside the others.

Caching

None at the provider level. The daily aggregation cache (src/daily-cache.ts) reuses prior computed days.

Quirks

The parser is in src/parser.ts, not in src/providers/claude.ts. Anything that changes Claude parsing belongs in parser.ts.
Streaming responses produce duplicate message IDs across resumed sessions; parser.ts strips them via the global seenMsgIds Set.
Model display names are mapped in claude.ts:7-20; add new versions there when Anthropic releases them.

When fixing a bug here

Confirm whether the bug is in discovery (sessions not picked up) or parsing (sessions found but data wrong).
Discovery bugs live in claude.ts:78-99. Verify the directory layout you expect actually matches what Claude writes today.
Parsing bugs live in src/parser.ts. Look for parseSessionFile, groupIntoTurns, and dedupeStreamingMessageIds.
Add a fixture under tests/fixtures/ and a test under tests/parser-claude-cwd.test.ts (or a new file). Do not mock the filesystem.

2.4 KiB Raw Permalink Blame History