ledger
Your project's memory, between sessions.
Claude Code forgets everything when the context window resets.
A /compact, a /clear, a closed terminal — and the goals, the decisions, the dead-ends you already ruled out, the exact line you were about to type all vanish. You spend the first ten minutes of every session re-explaining where you were.
ledger fixes that. It keeps a small set of living files that update themselves — so every session, even one that wakes up cold after a compaction, knows precisely what's done, what's in progress, what's blocked, and the exact next step.
It runs itself. You never call it.
Install · How it works · The living files · Safety · FAQ
CC BY-ND 4.0 · Claude Code plugin + standalone skill · zero-dependency core
The 30-second version
┌─ you open Claude Code in your project ──────────────────────────────┐
│ │
│ ── ledger · auto-catchup ── │
│ • Last session: auth refresh flow │
│ • Exact next step: │
│ Wire the 401-retry interceptor in src/lib/api.ts:refresh() │
│ — the cookie approach was abandoned (service-worker race). │
│ • In progress: │
│ - [~] wire 401-retry interceptor in src/lib/api.ts │
│ • Blocked: │
│ - [!] OAuth callback — blocked: Google console access pending │
│ • Commits since last session: 3a1f2e9 add refresh stub │
│ • Working tree: 1 uncommitted file(s). │
│ │
└──────────────────────────────────────────────────────────────────────┘
That briefing appears before your first message — injected automatically at session start. You didn't ask for it. You don't have to remember the dead-end you already walked. You just continue.
When the session ends — or Claude Code compacts mid-task — ledger snapshots everything back to disk, automatically. The loop closes. Nothing is lost.
Install
ledger ships two ways. The plugin is the one most people want: it wires the automation for you.
As a plugin (recommended — it runs itself)
# in Claude Code:
/plugin marketplace add realdeal88/ledger
/plugin install ledger@ledger
That's it. The five hooks register on install. Open any project, run /ledger init once, and tracking is live.
As a standalone skill (the /ledger command, no auto-hooks)
If you only want the /ledger command and would rather not install hooks, drop the skill in:
git clone https://github.com/realdeal88/ledger
cp -r ledger/skills/ledger ~/.claude/skills/ledger
Now /ledger, /ledger handoff, /ledger catchup, and /ledger init work. You call them by hand — the auto-catchup and auto-snapshot magic comes from the plugin's hooks, so for the full hands-off experience, prefer the plugin.
Heads up on namespacing. Installed as a plugin, the command is /ledger:ledger (Claude Code namespaces plugin skills). Installed as a standalone skill, it's just /ledger.
Quickstart
# 1. open Claude Code in a project
# 2. lay down the living files (once per project — never overwrites anything):
/ledger init
# 3. ...just work.
From here you do nothing special. As you go, ledger keeps the files current. The next time you open the project — or the moment Claude Code compacts — your state is already saved and already read back.
To force a rich, hand-written handoff before you walk away:
/ledger handoff
To restore full context on demand:
/ledger # or: /ledger catchup
How it works
The design rule is one line: the discipline is hook-enforced, not memory-dependent. Every tracking system that relies on the model remembering to update state fails the same way — the one session that forgets is the one that crashes, and the state is gone. ledger guarantees the writes mechanically through five non-blocking hooks, and lets you enrich them.
