An AI agent finishing a commit knows a lot. It knows the three approaches it tried before the one that worked, the constraint it tripped over, the part of the change that’s load-bearing and the part that’s a placeholder. Then the session ends and all of it goes away. The next agent opens the same file, sees something that looks wrong, and helpfully fixes it.

The big idea in Git Chronicle was to write the learnings into git notes. Git notes is this dusty corner of the ecosystem - entirely ignored by Github - but it’s almost perfect for this kind of metadata that should live outside the filesystem itself. I think my biggest takeaway is that there’s a great product to be built that makes the most out of it.

Chronicle is a git extension that writes that reasoning down before it evaporates. After a commit, the agent hands it a small JSON annotation: a summary of why this approach, plus a list of lessons tagged as a dead_end, a gotcha, an insight, or an unfinished_thread, each optionally pinned to a file and line range. The annotations live in git notes on their own ref, so they travel with the repo and need no server. Before touching a file, an agent runs git chronicle read <file>, which walks git log --follow to find the commits that shaped it and returns what each one left behind.

git chronicle setup installs Claude Code skills and hooks so agents do both halves without being asked: read before editing, annotate after committing. There’s also a knowledge store for repo-wide conventions and anti-patterns, a TUI, a web viewer, and a GitHub Action that stitches annotations back together after a squash merge.

I built it over about five days in February 2026, mostly by directing Claude Code, and shipped it to crates.io through a CI release bot. It annotated itself along the way, which made for a decent stress test. Tree-sitter parsing went in and came back out a day later, because agents already know which function they’re editing. An LLM-driven backfill path went too: the agent writing the code is the one holding the context, so asking it directly is instant and free.

The harder question was whether any of this helps. The code itself and git history provies a lot of inherent context, and connectivity from things like Linear or Github issues can also fill in gaps for an agent. I built a small eval harness with an LLM judge and ran Chronicle against a control to attempt to score this. The only clear win: tracking rejected decisions to prevent future revisiting of those paths. I think that’s useful, but not so useful to change my whole workflow around it.

This project has been archived.

cargo install git-chronicle