AIRECEIPTS

Docs ledger

Troubleshooting & FAQ

Rendered from docs/guide/12-troubleshooting.md.

Troubleshooting & FAQ

Symptom first. Find what you're seeing, then the fix. For question-first answers — how this differs from usage dashboards, what the dollars mean, what leaves your machine — see the FAQ.

"no agent session data detected"

no agent session data detected. Looked in:
~/.claude/projects, ~/.codex/sessions, ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb, ~/.gemini/tmp, ~/.local/share/opencode

aireceipts found no transcripts in any of the places it looks. The message lists those places verbatim, so the fix is usually one of:

  • You haven't run a session yet. Run your agent once, then try again — the receipt is built from the transcript it writes to disk.
  • Your agent stores logs elsewhere. aireceipts reads the default locations above. Claude Code honors $CLAUDE_CONFIG_DIR: if you've set it, aireceipts reads $CLAUDE_CONFIG_DIR/projects instead of ~/.claude/projects.
  • The files aren't readable. aireceipts silently skips a transcript it can't read (wrong owner, restrictive mode) rather than erroring on it. If a directory is present but its sessions don't show up, check the file permissions.

The default human receipt and --list print this as informational guidance and exit 0. Machine exports such as --json and --csv still exit non-zero with no sessions, because they would otherwise report success without a payload.

no session matched "…"

no session matched "does-not-exist-xyz"

Your selector — an index, a session id, or a title substring — matched nothing. Run aireceipts --list to see the exact titles and their 1-based indices, then select by an index or a substring you can see in the list. See Read a receipt.

The receipt shows tokens, not dollars

This is a feature, not a bug. When a session ran on a model that has no cited, dated price row, aireceipts prints the token counts and no price table matched — it never guesses a dollar figure it can't source:

--------------------------------------------------
TOTAL....................................3,325 tok
no price table matched

The whole tool rests on never printing a fabricated dollar. A tokens-only receipt means "I won't invent a number," not "something failed." Add a price for the model (one cited PR) and it prices from then on. Why, and how pricing works: How pricing is estimated.

A one-time note about diagnostics on first run

The very first time you run aireceipts, it prints this once:

aireceipts sends anonymous, content-free diagnostics and feature-usage events (command, coarse buckets, and a random install identifier — never transcript content, prompts, file paths, repo names, or dollar amounts). Disable anytime with AIRECEIPTS_TELEMETRY=off or DO_NOT_TRACK=1. Run --telemetry-show to see exactly what a run would send. Details: docs/telemetry.md

It never prints again after that. To turn telemetry off entirely (zero network calls — not "less," zero), set either environment variable:

export AIRECEIPTS_TELEMETRY=off      # or DO_NOT_TRACK=1

To see exactly what a run would send — and send nothing — run aireceipts --telemetry-show. Full detail: docs/telemetry.md.

Turn off the automatic session-end receipt

If you ran install-hook and want it gone:

aireceipts uninstall-hook
Removed the aireceipts SessionEnd hook.

It removes only the aireceipts hook and leaves your other Claude Code settings untouched. See Install the agent hook.

The week total didn't change

aireceipts week covers a moving window — the trailing seven days ending now — and buckets each session by when it ended. A session older than seven days, or one with no recorded end time, won't appear. To inspect a fixed span, pin it with --since <date> (see Aggregate the week).

Next