If you've ever watched Claude Code choke mid-task because it hit the model's context window, or worse, get brutally summarized and lose details it couldn't recover—you're not alone. Context window limits are the silent killer of long-horizon coding agent sessions. A new open-source tool called Context Ledger, built by wiztek-llc, takes a different approach: instead of fighting context limits, it uses your git history as an external memory store, letting Claude Code run roughly 28 times longer before hitting that wall.

The Core Problem With AI Coding Agents

Building software feature-by-feature with an AI agent is great until the accumulated context—file reads, reasoning traces, tool outputs, diffs—consumes the entire context window. At that point, the model either fails mid-task or gets compacted in ways that destroy important details. Naive truncation forgets the oldest work entirely. Rolling summarization loses specifics in prose. Neither approach is restorable: once it's gone, it's gone. Context Ledger calls this "restorable compression"—drop the content, but keep the handle.

How Git Commits Become Memory Boundaries

Context Ledger's insight is elegant: git commits are natural semantic boundaries where work is considered "done." When a feature gets committed, its roughly 10k tokens of build context get replaced with a compact ledger entry (about 300 tokens) plus a SHA pointer back to the exact commit. The key is that everything else is recoverable from git on demand—when later work needs an evicted detail, the agent rehydrates it via git show . Your committed code and git history become the external memory store. The ledger file persists across sessions (injected via a SessionStart hook) and after compaction events.

Benchmarks: Retention vs. Context Cost

The project's benchmarks on a real 4-feature build tell a compelling story. Using factual probes about earlier features, evaluated by the same model for every strategy: - Full (no compaction): 93% retention, but 33,347 resting context tokens—hits the wall at ~24 features - Truncate (last 8k): 64% retention, 8,016 tokens—loses oldest facts entirely - RollingSummary: 57% retention, 4,440 tokens—the prose loses specifics - Ledger: 93% retention matching Full, but only 6,411 answer-context and 1,223 resting context tokens—doesn't hit the wall until ~673 features

Installation: Get Started in Minutes

Getting Context Ledger running is straightforward. Clone the repo, run the install script, and optionally enable Claude Code hooks for automatic integration: git clone https://github.com/wiztek-llc/context-ledger && cd context-ledger && ./install.sh The CLI works standalone or with hooks enabled (--with-hooks during install). With hooks active, Context Ledger records ledger entries automatically after every git commit (via a PostToolUse hook) and re-injects the ledger at session start. The ./install.sh --no-hooks flag skips Claude Code integration if you just want CLI access.

Essential CLI Commands

Once installed, these commands handle most workflows: ctxledger doctor checks whether Context Ledger is wired up correctly in your project and tells you what to do next; ctxledger record extracts the HEAD commit and appends a ledger entry manually; ctxledger show prints your project's full ledger for inspection; ctxledger rehydrate [path] recovers exact evicted details from git when needed; and ctxledger stats shows features recorded, tokens saved, and compression ratios. Run ./run_all.sh to reproduce the complete benchmark suite including scaling charts and retention scoreboard—deterministic parts run offline, while the retention benchmark uses cached LLM calls stored in bench/cache/.

Honest Tradeoffs Worth Knowing

Context Ledger's RESEARCH.md acknowledges limitations: retrieval can miss; rehydration costs tokens when invoked (though only on demand); and the commit boundary is good but imperfect as a semantic seam. The approach also requires discipline—commits need meaningful messages since decision rationale lives there. But for teams already following conventional commit hygiene, this is essentially free memory management that makes long agent sessions viable without sacrificing recall accuracy.

Key Takeaways

  • Context Ledger replaces ~10k tokens of build context with ~300-token ledger entries + git SHA pointers at natural commit boundaries
  • Benchmarks show 93% factual retention matching full-context runs while using 30× less working context
  • Projects to run ~28× longer before hitting the 200k window (673 features vs. 24 without compaction)
  • Installation takes minutes via ./install.sh with optional Claude Code hooks for automatic operation
  • The ledger survives session restarts and manual context compaction events through persistent storage in /.claude/context-ledger.md

The Bottom Line

Context Ledger is the most practical solution I've seen for the context window problem that plagues long AI-assisted coding sessions. It doesn't require you to change how you work—just commit your features as normal and let git do what it's already doing anyway. If you're building anything nontrivial with Claude Code, this is worth five minutes of setup time.

> From The Wire