DEV Community

Cover image for Your Claude Code session dies at the context limit. This plugin leaves a ledger so the next one can continue.
ddk
ddk

Posted on Edited on

Your Claude Code session dies at the context limit. This plugin leaves a ledger so the next one can continue.

The worst moment

The worst moment with Claude Code is not a wrong answer. It is this:

400 ... maximum context length
Enter fullscreen mode Exit fullscreen mode

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*.jsonl and 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Then, in the project you want recorded: /ai-tracedoc-mods:on. Three commands in all: on, off, version.

Known limitations — read these before installing

  1. 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.
  2. 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*.md and *-tracedoc*.jsonl to .gitignore first.
  3. Q&A only. If you want a full event trace for debugging, this is not that.
  4. 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)