atomchung

atomchung / ccstory

Public

Claude Code usage recap with narrative. ccusage tells you the bill, ccstory tells the story.

pypi.orgprojectccstory analytics ccusage claude claude-code cli
10
1
85% credibility
Found May 17, 2026 at 24 stars -- GitGems finds repos before they trend. Get early access to the next one.
Sign Up Free
AI Analysis
Python
AI Summary

ccstory is a local tool that reads your Claude Code conversation logs and creates a personal recap of what you worked on. It categorizes your sessions into buckets like coding, writing, or investment, shows you time spent per category, and generates narrative summaries of your work. The tool runs entirely on your computer, reading only from your local Claude Code data. It creates markdown reports showing your activity patterns, compares current periods to previous ones, and can export notes in Obsidian format. Think of it as a fitness tracker for your AI assistant usage—helping you understand where your time and money went.

How It Works

1
💡 You discover ccstory when curious about your AI usage

You recently started using Claude Code and wonder where all that time and money went. You hear about a tool called ccstory from a friend or online.

2
📦 You install ccstory with a single command

You run a quick installation command, and the tool is ready on your computer. Nothing complicated, just one line and you're set.

3
🗂️ First run tells you what you worked on

When you run ccstory, it automatically looks at your Claude Code conversations and groups them into categories like coding, writing, or research. You see a breakdown of your time.

4
✨ You get a beautiful recap card in your terminal

A colorful summary appears showing your top focus, total hours, and how your time was distributed. It feels like opening a fitness tracker for your AI assistant.

5
Choose how detailed you want your story
⚡
Quick mode - instant results

Get your recap right away using the first message from each conversation as a quick summary.

🤖
Smart mode - AI-written summaries

Let the AI write proper descriptions of what you did in each session. Takes a bit longer but tells a much better story.

6
📊 You see trends over weeks or months

You run ccstory trend to see how your focus shifted over time. Which projects took most of your attention? Are you spending more time coding lately?

🎉 You write your weekly status without scrolling

You open the detailed report file and copy what you need. Your manager sees what you shipped, your investment research was organized, and you feel good about your productive week.

Sign up to see the full architecture

5 more

Sign Up Free

Star Growth

See how this repo grew from 24 to 10 stars Sign Up Free
Repurpose This Repo

Repurpose is a Pro feature

Generate ready-to-use prompts for X threads, LinkedIn posts, blog posts, YouTube scripts, and more -- with full repo context baked in.

Unlock Repurpose
AI-Generated Review

What is ccstory?

ccstory is a Python CLI that turns your Claude Code session logs into plain-English weekly or monthly recaps. It reads the JSONL files Claude Code generates locally, groups sessions by activity type (coding, writing, investment, research), and produces reports with per-session narratives, time breakdowns, and API-equivalent cost estimates. The tool runs entirely offline from your own data, using your local Claude Code installation to polish the prose when you opt in. Reports save as markdown files, with an Obsidian export mode that adds YAML frontmatter and wikilinks for PKM vault users.

Why is it gaining traction?

The hook is narrative. Most Claude Code tracking tools show you numbers (token counts, costs, session counts), but ccstory tells you what you actually did. It uses a 5-minute gap heuristic to estimate active time, categorizes projects by folder name, and can reclassify sessions by actual content when folder rules fall short. The comparison feature shows week-over-week shifts with a short prose synthesis, which is genuinely useful for anyone writing weekly status reports. Running `ccstory init` auto-suggests category buckets via one Claude Code call, which lowers the setup friction considerably.

Who should use this?

Freelancers and contractors who bill by the hour will like having concrete narratives ready for client updates. Solo developers doing retrospective work every Sunday can automate the "what did I ship" roundup. Teams using Obsidian or similar PKM tools get reports that drop into their vaults with queryable metadata. Anyone already running ccusage and wanting the "story behind the bill" will find the pairing complements their workflow.

Verdict

ccstory solves a real problem (context-switching tax on writing status updates) with a thoughtful implementation that respects privacy. The credibility score sits at 0.85%, reflecting a very small footprint with only 10 stars and early-stage maturity. The README is excellent and the feature set is coherent, but test coverage and documentation depth are minimal. Install it, run `ccstory init`, and try `ccstory week` if you want the narrative layer that usage tracking alone cannot provide.

Sign up to read the full AI review Sign Up Free

Similar repos coming soon.