What it does
Most AI coding failures are retrieval failures. The model is fine; the context it received was wrong. CodeLedger makes that layer visible: given a task description, it scores every file in the repository, bundles the highest-signal ones, and records the bundle it produced.
After you finish the work, CodeLedger compares the files it predicted against the files you actually changed. That gap is a measurable number, and it is the number that tells you whether your context layer is working.
Everything runs on your machine. On the free tier no repository content, embedding, or telemetry is transmitted; state lives in a local .codeledger/ directory you can inspect or delete.
Who it’s for
Engineers and instructors who want to study retrieval quality directly, without standing up a service.
What you need
- ·Node.js 18 or newer
- ·A git repository to run against
- ·No account, no API key
Quick start
# install & run$ npm install -g @codeledger/cli$ cd your-repo && codeledger init$ codeledger doctor
Requires Node.js 18+. Free tier, no signup. Watch for the unscoped codeledger package on npm — that's an unrelated tool from a different developer; the one above (@codeledger/cli) is ours.
Optional: the CodeLedger Panel Chrome extension shows a toolbar status badge and a local review signal on GitHub PRs. No telemetry; talks only to the CLI on your own machine.
Step by step
- 01
Install the CLI
Install globally so the codeledger command is available in any repository on your machine.
$ npm install -g @codeledger/cli - 02
Initialize inside a repository
init creates a local .codeledger/ directory holding configuration and scoring state. Nothing is uploaded.
$ cd your-repo$ codeledger init
- 03
Confirm the environment is healthy
doctor checks git, Node, configuration validity, and ambient readiness for terminal, Claude Code, browser, and IDE use.
$ codeledger doctor - 04
Score a task and read the bundle
Describe the change you are about to make, then inspect the ranked bundle CodeLedger proposes before you open a single file.
What you’ll see
✅ ContextECF CodeLedger v0.10.74 initialized Ambient readiness: ready for terminal, Claude Code, browser/cloud, and IDE/desktop. Stored locally in .codeledger/ — nothing leaves your machine. CodeLedger Doctor================================================== ✅ Git: git version 2.39.5 ✅ Node.js: v22.23.2 (>= 18 required) ✅ Config: Valid (v0.10.74) ✅ Ambient readiness: Ready for terminal, ambient wrappers, Claude Code, browser/cloud, and IDE/desktop use All checks passed. CodeLedger is healthy.
If something goes wrong
The codeledger command does something completely different.
You likely installed the unscoped codeledger package, which is an unrelated tool. Uninstall it and install @codeledger/cli instead.
doctor reports an invalid config.
Delete the local .codeledger/ directory and run codeledger init again; the directory is disposable local state.
Related
- CodeLedger Panel (Chrome extension) — Local-only status badge and PR review signal.
- ContextECF CodeLedger site