Troubleshooting

The portfolio is empty or stale

Run:

cc-analyzer claude-dir
cc-analyzer index --check
cc-analyzer index

The first command shows every configured Claude root and its source. The index only includes the configured roots, so reindex after changing them.

A session cannot be found

analyze and doctor accept either a session id or a .jsonl path. Confirm the file exists under the configured Claude directory. For another directory, use --claude-dir=<path> on those direct-file commands.

The TUI does not start

The TUI needs an interactive terminal. Use cc-analyzer stats or cc-analyzer serve --open in scripts, CI, or terminals without a TTY.

A report is missing newer sessions

Index-backed views read the cache. Run cc-analyzer index; for the web app use cc-analyzer serve --refresh.

Analyze-with-Claude is unavailable

The optional handoff needs a local claude executable on PATH (or Claude Code's local installation). Without it, ordinary parsing and analysis still work.

A session's cost is lower than my statusline or /cost

Expected, and not a bug. Claude Code's total_cost_usd also covers model calls it never writes into the transcript: session titling, away recaps, compaction, auto mode, subagent naming, tool-result summaries, hook prompts, and retried stream attempts. cc-analyzer can only price what the transcript records, so a session's cost is a floor for what the conversation itself cost.

On long, hook-heavy, auto-mode sessions the gap has measured 7-9%. It is smaller on short sessions, and it scales with prompt, tool and hook count rather than with token volume, so no fixed correction factor would be right. Nothing on disk records the difference, so no setting or reindex recovers it.

If the gap looks far larger than that, it is worth checking. The Cost & Pricing reference lists the checks that rule out a pricing or token-counting cause, including how to read Claude Code's own rate table out of its binary.

Export or parsing problems

Use doctor <id|path> --json and inspect parse coverage in the report. ZIP exports additionally require the system zip command. Exported artifacts can be large when transcripts are included, so try without --include-transcript first.

For implementation details, see the CLI reference, Web/API reference, and Core analysis reference.