Getting Started
Quick start
From zero to your first context bundle in five minutes.
Install CodeLedger
npm install -g @codeledger/cli
npx @codeledger/cli.npx â those sandboxes often can't reach the npm registry reliably. Run codeledger init once on your own machine first; it vendors a standalone binary into .codeledger/bin/ that works with zero network access once committed.Initialize your repo
Run this once inside your repo. It creates a .codeledger/ directory, writes a default config, and seeds the memory ledgers.
npx @codeledger/cli init
.codeledger/ is safe to commit. Add .codeledger/cache/ to your .gitignore to skip the index cache.Scan the repo
Builds the dependency graph, test map, churn history, and co-commit index. Takes 10â30 seconds on large repos.
npx @codeledger/cli scan
The scan output shows your repo's Coupling Index, Hotspot Score, and top risk drivers. Re-run after major refactors.
Activate for a task
Describe your task in plain English. CodeLedger scores every file and writes a ranked bundle to .codeledger/active-bundle.md.
npx @codeledger/cli activate --task "add rate limiting to the API gateway"
Read the bundle
The bundle lists files ranked by relevance score, with reasons and code excerpts. Start here instead of grepping the repo.
cat .codeledger/active-bundle.md
Typical bundles include 12â25 files out of thousands, covering 95%+ of the files you'll actually edit.
See your session recap
After you finish coding and commit, check how well the bundle predicted your actual edits.
npx @codeledger/cli session-summary
Optional: see it live, without a terminal open
Everything above works from the terminal alone. If you'd rather see status at a glance, the same local state is also available as a browser tab (codeledger panel serve) or a Chrome extension with a toolbar badge and a local review signal on GitHub PRs.