The worst moment
The worst moment with Claude Code is not a wrong answer. It is this:
400 ... maximum context length
You quit. You open a new session. And you spend the first ten minutes re-explaining what the project is, what you already changed, and why you changed it that way.
By the time it is caught up, you don't want to do it anymore.
I had a small project I hadn't touched in eleven days. Opening it again, I expected to start from scratch: what this is, where I left off, why I had done it that way. Instead I typed one line:
Read this project's
*-tracedoc*.jsonland carry on.
It answered: the parser work was finished, three cases were still uncovered, and the next step was boundary tests. I checked. It was right.
That was the moment I understood what I had built — not memory for the model, but a way to move "where this project got to" out of my head and onto the disk.
What it is
A Claude Code plugin (MIT). It runs as a hooks module — no binary. Every question you type and every final answer gets written to two files in your project root:
20261106-your-project-tracedoc.md for people
20261106-your-project-tracedoc.jsonl for machines, one line per Q&A
Only the questions a person writes and the model's final answer. Tool output, thinking, system reminders, other sessions' messages — none of it.
Past 200 KiB, a new session rolls into -02.md, with the JSONL following under the same name.
Isn't this just the built-in transcript?
This is the question I nearly didn't build the thing over. Claude Code does keep transcripts, at ~/.claude/projects/<encoded-path>/<session-uuid>.jsonl. The differences that mattered:
| Built-in transcript | This ledger | |
|---|---|---|
| Where it lives |
~/.claude/projects/…, on this machine |
the project root |
| Travels with the code | no | yes — commit it, or copy it over |
| What it holds | every event — tool calls, results, thinking | the questions and answers only |
| Granularity | one file per session | one ledger per project, appended across sessions |
| Meant for | replay and debugging | resuming, handover, review |
The built-in transcript stays on this machine; the ledger travels with the code. A machine switch, a handover, an AI picking the project up — all of it turns on that difference.
Twenty-one days of my own use
Not demo data — the ledgers on my own machine, counted as aggregates only:
- 6 projects, 287 Q&A turns
- about 407,000 characters
- 21 days, 13 of them active
- the largest single ledger: 110 turns
- the longest gap between two turns in one ledger: 11 days — and it kept writing after that
That last one surprised me. A project untouched for two weeks, and a new session simply picked it up.
Install
Requires Claude Code ≥ 2.1.287. Older versions do not load hooks modules — installed, it records nothing.
/plugin marketplace add https://github.com/didongke/ai-tracedoc-mods
/plugin install ai-tracedoc-mods@ai-tracedoc-mods
Then, in the project you want recorded: /ai-tracedoc-mods:on. Three commands in all: on, off, version.
Known limitations — read these before installing
- Do not run two Claude Code sessions in the same project. The ledger is read-modify-written as a whole, with no cross-process lock; two sessions writing at once overwrite each other and lose entries. It tries to detect this and asks you to close one — do not rely on it.
-
The ledger sits in the project root and will be committed unless you ignore it. If your Q&A may contain secrets, internal hostnames or client names, add
*-tracedoc*.mdand*-tracedoc*.jsonlto.gitignorefirst. - Q&A only. If you want a full event trace for debugging, this is not that.
- Run on Windows, Linux and macOS, with 78 checks in the test suite — but there are certainly edges it does not cover.
Why verbatim, not summarized
Most "automatic documentation" has a model write a summary afterwards. This does not, because of one plain principle:
The decision is not in the summary. It is in your next question.
You ask "why LRU"; the model answers; you say "let's go with that". The decision chain already exists in the sequence of questions and answers, and distilling it loses exactly what a future reader wants. The consequences are direct: recording never calls a model, so no tokens, no hallucination, and no translation — Chinese stays Chinese.
What I'd like to know
If you install it, tell me one thing: what does your project actually do, and did the ledger ever save you from re-explaining it?
Three things I am especially curious about:
- is it a solo project, or a team?
- have you actually resumed across days?
- would you rather it recorded more (say, a tool-call summary), or stayed lean?
"It never once helped" is a useful answer too — it tells me to stop spending time on this.
Bugs go to the issue tracker (the forms are there); use cases and questions to Discussions.
The code is the project's present; the ledger is its history.
GitHub: didongke/ai-tracedoc-mods · MIT
Top comments (0)