codeburn/docs/providers/claude.md

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: tests/providers/claude-cowork-ledger.test.ts and tests/providers/claude-cowork-ledger-readonly.test.ts, plus tests/parser-claude-cwd.test.ts, tests/parser-filter.test.ts, and tests/parser-mcp-inventory.test.ts.

Where it reads from

Source	Path
Claude Code CLI	$CLAUDE_CONFIG_DIR if set, otherwise ~/.claude/projects/
Claude Desktop (macOS, classic)	~/Library/Application Support/Claude/local-agent-mode-sessions/
Claude Desktop (macOS, 3p/Cowork)	~/Library/Application Support/Claude-3p/local-agent-mode-sessions/
Claude Desktop (Windows, classic)	%APPDATA%/Claude/local-agent-mode-sessions/
Claude Desktop (Windows, MSIX)	%LOCALAPPDATA%/Packages/<Claude package>/LocalCache/Roaming/Claude/local-agent-mode-sessions/
Claude Desktop (Linux)	~/.config/Claude/local-agent-mode-sessions/

From October 6, 2026, new Claude Cowork tasks on Pro and Max plans run in Anthropic's cloud instead of on your computer, so they no longer write local session files and CodeBurn can't price them. Tasks started on your computer before then are still read. Plan limits are unaffected: the Claude quota windows come from Anthropic's own usage figures, which include cloud Cowork. Claude Code runs locally and is tracked as before.

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

Desktop session roots are resolved in this order:

1. A non-empty CODEBURN_DESKTOP_SESSIONS_DIR overrides discovery and is the only returned root.
2. macOS checks both the classic Claude path and the Claude-3p Cowork path.
3. Windows always includes the classic path first. It then scans %LOCALAPPDATA%/Packages for package directories whose names start with Claude_ or contain .Claude_, sorted by package name, and includes only packages whose full MSIX sessions path exists as a directory.
4. Other platforms use the single Linux path shown above.

All returned roots are absolute, resolved, and deduplicated. Missing or unreadable Windows package directories are ignored.

Storage format

JSONL, one event per line, per session file. Sessions live under <project>/<sessionId>.jsonl. Claude Desktop 3p also writes usage-ledger/*.ndjson records under its local-agent-mode-sessions root. Both surface: "cowork" and surface: "code" records are included and labeled Claude Cowork and Claude Code, respectively.

A ledger record and a JSONL transcript can describe the same API call. The transcript call is kept, since it carries the project, tools, and turn classification, and a ledger call is dropped only when its model, token counts, and timestamp match a transcript call within 30 seconds. This keeps the request counted once while retaining it when the transcript is later deleted.

Parser

src/parser.ts reads Claude JSONL files directly with full turn grouping, dedup of streaming message IDs, and MCP tool inventory extraction. createSessionParser reads the Desktop usage ledger, which is parsed through the shared provider cache so its records can be served independently of the transcript tree.

Claude Code can record a message sent while it is working as an attachment entry with attachment.type: "queued_command" and commandMode: "prompt". CodeBurn counts a timestamped, non-empty prompt as a new user turn and assigns later assistant API calls to it. Task notifications, IDE or system-reminder injections, slash commands, and other attachment types are ignored, as are peer and agent-message queued commands (isMeta: true/origin.kind: "peer"), which are queue plumbing rather than a prompt the user typed. Turns represent API usage, so a queued prompt with no following assistant API call is omitted, just like an ordinary user message with no assistant call.

Pricing

Claude Code reports total cache-write tokens in usage.cache_creation_input_tokens. When available, it also splits those writes by duration in usage.cache_creation.ephemeral_5m_input_tokens and usage.cache_creation.ephemeral_1h_input_tokens. CodeBurn keeps the existing aggregate cache-write token total for reports, but prices the 1-hour portion at 2x base input cost (1.6x the 5-minute cache-write rate exposed by LiteLLM). If the split fields are missing, the parser falls back to the legacy behavior and prices every cache write at the 5-minute rate.

For Desktop ledger records, CodeBurn uses the shared CodeBurn pricing table and configured price overrides for known model ids. The recorded ledger cost is used only as a fallback when CodeBurn has no billable price for that model, so changing Claude Desktop pricing does not replace a CodeBurn estimate. The raw model id remains available to pricing; route variants such as us.anthropic.… and global.anthropic.… are not collapsed for billing.

Bedrock sessions

The JSONL has no provider field; the only trace of how a call was billed is the model id. With CLAUDE_CODE_USE_BEDROCK=1 the assistant messages record Bedrock's id — anthropic.claude-haiku-4-5-20251001-v1:0, or with the cross-region profile prefix the user configured, us.anthropic.… — where a direct-API session records claude-haiku-4-5-20251001. getModelRoute reads the shape, so the rows are Haiku 4.5, Haiku 4.5 (Bedrock) and Haiku 4.5 (Bedrock us): three SKUs at three prices, kept apart on every surface (see "Model rows and billing routes" in ../architecture.md). Vertex ids (claude-…@20251001) are not a route yet; the @ suffix is stripped and they merge with the direct row.

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.

Early quota resets

Anthropic sometimes resets a usage window before its scheduled time. The menubar notices on the existing refresh lifecycle — no extra request — by comparing each fetch's windows against the previous fetch's readings, which are kept per window in UserDefaults alongside the record of what has already been announced. Everything is local; nothing is fetched to produce it. A detected reset posts one system notification and nothing else: there is no persistent UI for it.

The detection is deliberately quiet. It needs a validated window length (the fixed 5-hour and 7-day limits), a stored reset that has not yet passed, and either a reset time anchored to a genuinely new cycle or a fall of at least 40 points that lands at or under 10%. A scheduled reset, a plan change, clock or timestamp skew, a window appearing or disappearing, a first observation and a reconnect after a terminal failure all produce nothing.

When fixing a bug here

1. Confirm whether the bug is in discovery (sessions not picked up) or parsing (sessions found but data wrong).
2. Discovery bugs live in claude.ts:78-99. Verify the directory layout you expect actually matches what Claude writes today.
3. Parsing bugs live in src/parser.ts. Look for parseSessionFile, groupIntoTurns, and dedupeStreamingMessageIds.
4. 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.