ccstory

What ccstory reads and writes

ccstory is a command line tool that reads the local session logs produced by your coding agents and turns them into a plain English recap. The project describes itself as the story behind your AI coding week. Where the sibling project ccusage reports the bill, ccstory reports what the tokens were actually spent on. The recap is categorized, which means the tool groups work into buckets and attaches a per bucket narrative rather than showing a single number. ccstory reports active hours, costs, and a written summary for each category of work. The current release bundles support for three providers. These are Claude Code, OpenAI Codex, and Google Antigravity. The design includes a provider registry that is meant to let more agents be added later without changing the recap contract, so the output format stays stable as new agents are supported. The tool works entirely from local logs, so the categorization and narrative are built from data already on your machine. This makes the recap useful for anyone who wants to know not just how much was spent, but what kind of work consumed those sessions. The full report is saved to a markdown file you can read or share. Because the recap is written in plain language, it serves as a basis for a weekly status update without scrolling through raw session output.

How to install and run your first recap

The quick start path uses three commands. First run pipx install ccstory to install the tool. Then run ccstory init, which the README describes as a one time auto categorize step that scans your recent sessions. Finally run ccstory week, which produces the recap. The init step is meant to be run a single time, while the week command can be run whenever you want a fresh summary. When the recap is produced, the full report is saved to the path ~/.ccstory/reports/recap-*.md, where the star is filled in with a date stamp. The default report includes a section called Repo activity, and that section always reads your local git history. When GitHub access is connected, ccstory lightly enriches up to 10 active repositories with GitHub metadata. The demo shown in the README covers a week from May 5 to May 12 of 2026. In that example the top focus was coding at 10.9 hours, which was 53 percent of active time. The active total was 20.6 hours across 74 sessions, with 2.92 million characters of output and 3,692 turns. Those numbers show the kind of detail the recap surfaces for a normal week of agent use. The README frames the pair as ccusage telling you the bill while ccstory tells you the story, so the two tools cover cost and narrative separately.

Running with no network connection

ccstory supports a mode for machines that have no network access at all. For a first run with no network, the README suggests running ccstory init --skip followed by ccstory week --minimal --classify folder --no-artifacts. The init --skip flag avoids the network portion of the setup, and the week command uses the minimal flag with folder based classification to keep the recap local. The --no-artifacts flag alone disables ccstory's GitHub and PyPI lookups while keeping the normal narrative flow. The README notes that this mode may invoke one of your configured local coding agent command line tools, because the narrative still needs to read session data. This makes the tool usable on an offline workstation where you still want a structured recap of the work your agents did. The classification options let you group activity by folder, which is a plain way to see which parts of your repository received the most agent attention. Because the report is built from local logs and local git, no external call is required to produce a useful summary. You can run the same commands again later to refresh the recap as new sessions accumulate. This keeps ccstory useful on a locked down machine where only local files are available and no external API calls are allowed.

Who the weekly recap helps

The README lists three groups of people who get value from ccstory. The first group is people who want to write a weekly status without scrolling through scrollback. Instead of reading every line of agent output, they can read the categorized recap and lift the narrative into a status update. The second group is people who saw a ccusage number and want to know what kind of work those tokens went to. ccstory answers that question by attributing hours and output to buckets of work. The third group is people who do a Sunday night reflection on what they actually shipped, since the recap makes the week's activity concrete. The tool is a sibling to ccusage, and the README frames the pair as ccusage telling you how much you spent while ccstory tells you what on. Because the recap is written in plain English and stored as a markdown file, it is easy to paste into a chat or a document. The provider registry approach also means the same recap style will keep working as additional agents are added, so a team that adopts a new coding agent will not need a new reporting tool. The three audiences show the tool is aimed at reflection and reporting as much as at raw measurement of agent output.

Editorial conclusion

ccstory is written in Python under the MIT license and installs with the command pipx install ccstory, after which ccstory init and ccstory week produce a recap saved to the path ~/.ccstory/reports/recap-*.md.