Getting Started

Quick start

From zero to your first context bundle in five minutes.

npm install -g codeledger

💡No global install required — every command below also works with npx codeledger.

Run this once inside your repo. It creates a .codeledger/ directory, writes a default config, and seeds the memory ledgers.

npx codeledger init

ℹ️.codeledger/ is safe to commit. Add .codeledger/cache/ to your .gitignore to skip the index cache.

Builds the dependency graph, test map, churn history, and co-commit index. Takes 10–30 seconds on large repos.

npx codeledger scan

The scan output shows your repo's Coupling Index, Hotspot Score, and top risk drivers. Re-run after major refactors.

Describe your task in plain English. CodeLedger scores every file and writes a ranked bundle to .codeledger/active-bundle.md.

npx codeledger activate --task "add rate limiting to the API gateway"

💡If you use Claude Code, the UserPromptSubmit hook does this automatically — you never need to type it yourself.

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.

After you finish coding and commit, check how well the bundle predicted your actual edits.

npx codeledger session-summary

What's next

Context selection

How the scoring algorithm works

CI integration

Add PR risk signals to GitHub Actions

Command reference

Every flag for every command