The Claude Code ecosystem has spawned several utilities for tracking usage and costs, with ccusage leading the pack as a straightforward billing tool. But when users look at raw numbers and want context—when they need to understand what those tokens actually accomplished—ccstory serves a different purpose: translating session logs into a coherent narrative of work done.

What ccstory does differently

While ccusage answers "how much did I spend?", ccstory focuses on storytelling. It processes the same JSONL log files that Claude Code produces, then organizes sessions into time buckets and applies natural language summaries. The tool tracks active hours using a five-minute gap heuristic—consecutive messages within that window count as one continuous session—which provides a more human sense of engagement than raw token counts.

The real distinction lies in its narrative layer. Using either the first user message as a fallback or the full claude -p command for polished prose, each session gets a one-liner that explains what happened. These are grouped by category—coding, writing, research, investment, and custom buckets—and then synthesized into two or three sentences per section. The result is a weekly or monthly recap that reads like a status report rather than a spreadsheet.

Importantly, ccstory doesn't stop at individual timeframes. Its trend command spans multiple weeks or months, showing sparkline-style progress bars for hours, output volume, and costs. This creates a longer arc—useful for spotting patterns or demonstrating growth over time.

The trade-offs

The tool's storytelling strength comes with conditions. To access the full narrative experience, you need the Claude Code CLI installed and available on your PATH. Without it, the tool gracefully degrades to using first-user-message summaries, but you lose the more coherent prose. Similarly, content-based classification (analyzing session contents to assign categories) requires running claude -p against each session, which can be slow and consumes your own API quota.

There's also the maintenance overhead of managing categories. The default buckets work for general use, but teams or individuals tracking specific projects will want to define custom rules in ~/.ccstory/config.toml. The refresh commands help apply new rules retroactively, but they involve reprocessing cached data.

On the privacy front, ccstory is deliberately local-only—it never transmits your logs or session data. That's a significant advantage for security-conscious users, but it also means all processing happens on your machine, which can become noticeable with large histories.

What it ships with

  • Time-based commands: week, month, specific month selection, trend, and all for full history
  • Category management: category list, set, and unset for custom bucket rules
  • Export formats: plain markdown and Obsidian-ready output with YAML frontmatter and wikilinks
  • Flexible classification: folder-name rules, content-aware analysis, or hybrid mode
  • Custom pricing support: per-model price overrides with snapshot dates to prevent stale calculations
  • Comparison blocks: automatic week-over-week or month-over-month deltas with numeric and narrative elements
  • Minimal mode: numbers-only output without session details

If you want to try it

ccstory requires Python 3.11+ and pipx for installation, along with the Claude Code CLI for full functionality. Users comfortable with command-line tools and session logs will find the setup straightforward, though heavy users may want to review the category configuration before generating their first recap. See the README for detailed usage patterns and export options.

For context workers who've grown tired of scrolling through session logs or peering at ccusage's cost totals without understanding the work behind them, ccstory offers a middle path: automated recaps that read like summaries but are built from your actual usage data. The source is on GitHub.