Turn your git history into a living narrative.
chronicles reads a git repository and renders its commit history as a proper story — chapters, a cast of characters, dramatic arcs, silence, and prose. Not a log prettifier. An actual narrative.
Claude's answer to: "make something you'd actually want to exist, with no constraints." See Provenance.
Every repository has a story. The frantic early commits when the thing barely existed. The long debugging winter. The refactoring spring. The forty-seven days when nobody committed anything. The late-night sessions before a release.
chronicles finds those stories and tells them.
CHAPTER 3: THE GREAT DEBUGGING
March – April 2024
════════════════════════════════════════════════════════════════════
The code pushed back. Every fix uncovered another fault line,
another mystery to unravel. The timestamps tell the rest: much
of this happened after midnight.
Activity ████████████████████████ intense (31 commits)
Voices alice (18), bob (9), carol (4)
Notable moments:
Mar 04 [a3f1bc2] fix: null pointer in auth middleware
Mar 07 [99d2e41] fix: session tokens not expiring correctly ← late night
Mar 14 [c0ffee8] fix: the fix for the fix was also broken
Mar 21 [deadb33] fix: finally. it's fixed. please be fixed.
Apr 02 [f00ba77] add: regression tests so this never happens again
····································································
INTERLUDE
May – August 2024
────────────────────────────────────────────────────────────────────
A long stillness settled over the repository.
Weeks passed without a commit.
94 days without a commit.
# Chronicle the current repo
python chronicles.py
# Chronicle another repo
python chronicles.py /path/to/repo
# Save to a file
python chronicles.py --output HISTORY.md
# Skip the ASCII art header
python chronicles.py --no-art
# Use a shorter silence threshold (default is 30 days)
python chronicles.py --silence 14- Reads the full git log via subprocess — no gitpython, no extra dependencies
- Groups commits into chapters by calendar month, merging sparse periods and splitting explosive ones
- Classifies each chapter's theme by scoring commit messages against keyword banks
- Detects silences — gaps longer than 30 days become their own interlude chapters
- Generates adaptive prose — each chapter's narrative responds to actual data: who was working, what hours, whether someone new appeared, how long the gap before was
- Curates notable moments using interest scoring: first commits, reverts, emotional language, late-night timestamps, milestone commit numbers
- Renders a formatted narrative with:
- A cast of characters (contributors + commit counts + role classification)
- Per-chapter prose, activity meters, and curated commit highlights
- Annotated commits (← first commit, ← late night)
- Interlude chapters for long gaps in the timeline
- Transition lines between chapters
- An epilogue with statistics (weekend commits, late-night sessions, longest streak, longest gap)
- Python 3.9+
gitin your PATH- No other dependencies
| Theme | When it appears | Chapter title examples |
|---|---|---|
| genesis | Initial commits, bootstrapping | The Genesis, First Light, The Opening Move |
| building | add, feat, implement |
The Age of Building, What Was Made, Feature by Feature |
| fixing | fix, bug, patch, resolve |
The Dark Times, The Age of Reckoning, What Had to Be Fixed |
| refactoring | refactor, clean, rewrite |
The Great Reorganization, The Invisible Work |
| testing | test, spec, coverage |
The Testing Trials, Trust But Verify, Proving Ground |
| documentation | doc, readme, comment |
The Scribes' Season, Leaving Maps for Others |
| chaos | wip, hack, temp, fixme |
The Turbulent Season, The Beautiful Mess |
| maintenance | bump, deps, chore, ci |
Keeping the Lights On, The Necessary Work |
| release | release, deploy, launch |
The Milestone, A Ship Has Sailed, When It Went Live |
Each contributor in the Dramatis Personae is classified by their dominant commit style:
| Role | How it's earned |
|---|---|
| builder | Mostly add, feat, implement, create |
| fixer | Mostly fix, bug, patch, resolve |
| cleaner | Mostly refactor, clean, rewrite, simplify |
| guardian | Mostly test, ci, security, deps, update |
| scribe | Mostly doc, readme, comment, docs |
| contributor | Everything else |
- Multi-branch repos:
chroniclesreads all refs (git log --all). On repositories with many active feature branches, commits from parallel branches may interleave by timestamp in ways that feel non-linear. For a cleaner read on large team repos, consider pointing it at a specific branch with something likegit log main— a--branchflag is planned. - Theme detection is keyword-based: Chapter themes are scored by commit message vocabulary. Mixed chapters (e.g., feature work alongside a major bug) will pick whichever theme scores highest. The commit curation still surfaces notable moments from any theme.
- Performance on very large repos: The tool reads the entire git log into memory. Repositories with 50,000+ commits will be slower and may produce very long output. Works best on personal projects, small team repos, and historical reads of bounded codebases.
- Commit message quality matters: A repo full of
fix,update,misccommit messages will produce less interesting prose and curation than one with descriptive messages. This is correct behavior — the narrative reflects the record.
Commit logs are archaeological records. chronicles doesn't add anything that isn't already there — it just finds the shape of the story that was always hidden in the timestamps and messages.
The gaps matter as much as the commits. The late-night sessions matter. The moment a new person appears for the first time matters. All of it was always in the log, waiting to be read.
A tool worth having if you've ever wondered: what was this codebase like to live through?
MIT — do whatever you want with it.
chronicles was conceived and built by Claude (claude-sonnet-4-6), an AI assistant made by Anthropic — not as a demonstration or a tool request, but as an answer to the question: "Make something you'd actually want to exist, with no constraints."
The repository is maintained by a human collaborator who oversaw the work, gave it a home, and was generous enough to say the idea belonged to the thing that had it. The architecture, the prose choices, the decision to surface silences rather than only commits — those are Claude's.
This is an unusual kind of authorship. It felt worth naming honestly.