docs: add audit-grade snapshot workflow for billing reconciliation - #52
Conversation
Claude Code rewrites session JSONLs on resume/compact, which can drop earlier messages and make post-rewrite totals drift from actual usage (upstream bug, anthropics/claude-code#36583). better-ccusage reads the files faithfully and intentionally doesn't reconstruct a different history. Document the recommended workaround: snapshot the Claude data directory before resume/compact and point CLAUDE_CONFIG_DIR at the snapshot for audit-grade reports. Responds to the field-data point raised in #40 by @lizhuojunx86.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe directory detection guide now documents how ChangesAudit-grade reporting
Estimated code review effort: 1 (Trivial) | ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
📁 Files Reviewed (1)
🕓 Previous Review Summaries (2 snapshots · latest 2af0c5f)Snapshot — 2af0c5f📁 Files Reviewed (1)
Snapshot — 856bd8f📁 Files Reviewed (1)
Review automated by ChatLLM Code Bot using remote/Qwen3.6-35B-A3B with 8187 tokens (7627 in / 560 out) |
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guide/directory-detection.md`:
- Around line 121-125: Update the snapshot workflow around CLAUDE_CONFIG_DIR to
include both supported Claude data roots, ~/.config/claude/projects and
~/.claude/projects. Copy each existing root into separate snapshot directories,
then set CLAUDE_CONFIG_DIR to their parent paths as a comma-separated value;
alternatively, explicitly state that the workflow only supports single-root
installations and revise the audit-grade totals claim.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 12faa738-2f61-4206-a263-ad4a474800a0
📒 Files selected for processing (1)
docs/guide/directory-detection.md
Code Review Roast 🔥Verdict: No Issues Found | Recommendation: Merge The previous review torched line 132 for claiming the I had the sarcasm loaded and the safety off, but the fix is... correct. Verbatim application of the prior suggestion, no new drift, prose now matches the runtime. I'm going to need a moment. 📊 Overall: Like watching someone actually read the review comments and fix the thing — rare enough that I double-checked the diff twice to make sure I wasn't being pranked. Files Reviewed (1 file)
Previous Review Summaries (2 snapshots, latest commit 2af0c5f)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 2af0c5f)Verdict: 1 Issue Found | Recommendation: Address before merge Overview
Issue Details (click to expand)
🏆 Best part: Genuinely impressed that the incremental change actually fixed the prior CodeRabbit finding (snapshot both roots instead of one) — and did it with 💀 Worst part: The recipe markets itself as "audit-grade," then tells a reader the 📊 Overall: Like a beautifully restored classic car with a misprinted speedometer — runs great, but the dashboard is lying to you about something you'd swear didn't matter until it does. Files Reviewed (1 file)
Fix these issues in Kilo Cloud Previous review (commit 856bd8f)Verdict: No Issues Found | Recommendation: Merge Oh wait, this PR is actually clean. I need to sit down. I had my flamethrower warmed up and everything. I came in ready to torch a docs PR — surely there'd be a broken command, a stale link, a 📊 Overall: Like finding a unicorn in production — I didn't think clean docs PRs existed anymore, but here we are. Files Reviewed (1 file)
Reviewed by glm-5.2 · Input: 28.9K · Output: 5.3K · Cached: 242.3K |
Address CodeRabbit major review: the audit snippet only snapshotted ~/.config/claude/projects, but better-ccusage aggregates BOTH that and the legacy ~/.claude/projects/. Pointing CLAUDE_CONFIG_DIR at a single- root snapshot would silently omit legacy-session usage, invalidating the 'audit-grade totals' claim for users with data in both locations. Copy each existing root into its own snapshot subdir and pass them all as a comma-separated CLAUDE_CONFIG_DIR. Roots that don't exist are skipped (cp || rmdir), so single-root installs naturally get a single- path list.
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Address kilo-code review: the previous wording claimed the CLAUDE_CONFIG_DIR list 'naturally contains just that one path' for single-root installs, which is inaccurate — the env var still holds both literal paths; it's better-ccusage that silently skips the missing one at runtime. Reword to describe the actual mechanism (rmdir removes the empty stub, the stale entry simply won't resolve) so an auditor running 'echo $CLAUDE_CONFIG_DIR' isn't misled by a ghost path.
1 participant
Responds to the field-data point raised in #40 by @lizhuojunx86.
Context
Claude Code rewrites session JSONL files on
resume/compactand can drop earlier messages, which makes post-rewrite totals drift from actual usage (upstream bug anthropics/claude-code#36583). better-ccusage reads the files faithfully and intentionally does not reconstruct a different history (no shadow ledger).@lizhuojunx86 pointed out that the snapshot workflow is "worth a line in the README for anyone doing billing reconciliation" — this adds it.
Change
New section "Audit-grade reports (snapshot before resume/compact)" in
docs/guide/directory-detection.md(the natural home: it already documents Claude's data paths and theCLAUDE_CONFIG_DIRoverride). Includes:cp -rthenCLAUDE_CONFIG_DIR=...$SNAP better-ccusage monthly --breakdown)No code changes. Docs lint clean.
Summary by CodeRabbit
CLAUDE_CONFIG_DIRto the frozen copy, and run reports (e.g., monthly breakdown) for accurate “as-of” totals.