Skip to content

docs: add audit-grade snapshot workflow for billing reconciliation #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cobra91 merged 3 commits into from
Jul 20, 2026
Merged

docs: add audit-grade snapshot workflow for billing reconciliation #52

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
856bd8f
docs: add audit-grade snapshot workflow for billing reconciliation
cobra91 Jul 20, 2026
2af0c5f
docs: snapshot both Claude data roots in audit workflow
cobra91 Jul 20, 2026
dc9212e
docs: accurate single-root note for audit snapshot workflow
cobra91 Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/guide/directory-detection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,29 @@ better-ccusage daily
LOG_LEVEL=4 better-ccusage daily
```

## Audit-grade reports (snapshot before resume/compact)

Claude Code rewrites session JSONL files when you `resume` or `compact` a session, and in doing so can drop or rewrite earlier messages. Because better-ccusage reads those files faithfully, totals computed after a rewrite can drift from what you actually used earlier — historical usage that was compacted away is gone from the source.

This is an [upstream Claude Code behavior](https://github.com/anthropics/claude-code/issues/36583), not a better-ccusage bug, and better-ccusage intentionally does not reconstruct a different history (no shadow ledger). For billing reconciliation or audit-grade totals, snapshot the Claude data directory before resuming/compacting long sessions, then point `CLAUDE_CONFIG_DIR` at the snapshot when you need an accurate-as-of-then report.

better-ccusage aggregates **both** Claude data roots by default — the new `~/.config/claude/projects/` and the legacy `~/.claude/projects/` (see [Default Directory Locations](#default-directory-locations)). A correct snapshot must capture each root that exists on your machine, then report against all of them via a comma-separated `CLAUDE_CONFIG_DIR`:

```bash
# 1. Snapshot every Claude data root that exists (do this before resume/compact)
SNAP="$HOME/claude-snapshots/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SNAP/config" "$SNAP/legacy"
# Copy each existing root; ignore the ones you don't have.
cp -r ~/.config/claude/projects "$SNAP/config/projects" 2>/dev/null || rmdir "$SNAP/config"
cp -r ~/.claude/projects "$SNAP/legacy/projects" 2>/dev/null || rmdir "$SNAP/legacy"

# 2. Later, run reports against the frozen snapshot (list every root you copied)
export CLAUDE_CONFIG_DIR="$SNAP/config,$SNAP/legacy"
better-ccusage monthly --breakdown # totals as of the snapshot date
```

If you only have one root (e.g. a fresh install on `~/.config/claude`), `rmdir` removes the empty stub for the missing root and better-ccusage silently skips it, so the report still runs against the one root you copied (the stale entry in `CLAUDE_CONFIG_DIR` simply won't resolve). Keep snapshots around for as long as you need auditable numbers; they're plain JSONL files, so they compress well. See [#40](https://github.com/cobra91/better-ccusage/issues/40) for the original field report and repro.

## Related Documentation

- [Environment Variables](/guide/environment-variables) - Configure with CLAUDE_CONFIG_DIR
Expand Down
Loading