Provides AI coding agents with task-relevant repository context and evidence-backed file bundles to improve accuracy and reduce token usage.
Also known as codeledgerECF/codeledger, @codeledger/cli
- Stars
- 8
- Tools
- —
- Downloads, 30 days
- 4,468
- Latest version
- 0.10.82
- Last commit
- Nov 11, 2026
- License
- —
What is CodeLedger MCP?
CodeLedger provides AI coding agents with task-relevant repository context and evidence-backed file bundles to improve accuracy and reduce token usage.
Summary generated from the project's README
About CodeLedger MCP server
CodeLedger provides local-first context control for AI coding agents to improve accuracy and reduce token consumption. It works by scanning a repository for signals like dependency structure and test files to select a bounded set of task-relevant files. This information is written to a specific artifact at .codeledger/active-bundle.md, which agents like Claude Code, Cursor, or GitHub Copilot can read before starting work.
Developers use the CLI to initialize repositories and prepare for specific tasks using the ready command. The tool runs analysis locally by default and does not send source code through telemetry. It includes an MCP server that can be started via the command line to integrate with compatible clients. Users can also run a compare command to measure performance improvements across metrics like token usage and test pass rates.
What you can do with it
- 1Prepare task-specific contextAn AI agent can receive a focused bundle of files relevant to a specific bug fix or feature request.
- 2Verify agent changesUsers can review what an agent modified through session summaries and receipts.
Written from the project's README. Every use case is checked against a quote from it.
How to install CodeLedger MCP
Formats verified 10 Nov 2026Install CodeLedger MCP in Claude Code
$ claude mcp add codeledger -- npx -y @codeledger/cliInstall CodeLedger MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codeledger": {
"command": "npx",
"args": [
"-y",
"@codeledger/cli"
]
}
}
}Install CodeLedger MCP in VS Code
.vscode/mcp.json
{
"servers": {
"codeledger": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codeledger/cli"
]
}
}
}Install CodeLedger MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codeledger": {
"command": "npx",
"args": [
"-y",
"@codeledger/cli"
]
}
}
}Install CodeLedger MCP in Codex
~/.codex/config.toml
[mcp_servers.codeledger] command = "npx" args = ["-y", "@codeledger/cli"]
Install CodeLedger MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"codeledger": {
"command": "npx",
"args": [
"-y",
"@codeledger/cli"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecodeledgerecf/codeledger is public and reachablegithub.com/codeledgerecf/codeledger ↗Pass
- Package names this repository as its source@codeledger/cli names github:codeledgerECF/codeledger as its sourcenpmjs.com/package/@codeledger/cli ↗Finding
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-11github.com/codeledgerecf/codeledger ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @codeledger/cliPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodeLedger
Give AI coding agents the right repo context before they start - then verify what changed.
CodeLedger is local-first context control for AI coding agents. It scans a repository, selects a bounded task-relevant set of files, and writes an evidence-backed context bundle before the agent begins work.
Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and other CLI or MCP-compatible coding agents.
Try It
npm install -g @codeledger/cli
cd your-project
codeledger ready --task "Fix null handling in user service"
CodeLedger initializes the repo if needed, refreshes the index, and creates the
task-specific bundle at .codeledger/active-bundle.md. Your agent reads that
artifact first so it starts with the files most relevant to the task.
Runtime analysis is local by default. Installing or updating may fetch packages or release artifacts from npm and GitHub Releases; CodeLedger runtime analysis does not send your source code through CodeLedger telemetry by default.
Example Benchmark
Example result from a mid-sized Node.js service. Results vary by repository, task, agent, and scenario.
| Metric | Without CodeLedger | With CodeLedger | Change |
|---|---|---|---|
| Tests Passed | 78% | 94% | +16% |
| Iterations | 4 | 2 | -50% |
| Files Changed | 17 | 9 | -47% |
| Time to Finish | 6m 12s | 3m 40s | -41% |
| Token Usage | 28k | 18k | -36% |
Do not take the benchmark on faith - measure CodeLedger on your own repo:
codeledger compare \
--scenario .codeledger/harness/scenarios/auth-rate-limit.json \
--guided
If CodeLedger improves your coding-agent workflow, star the repo to follow releases and help other developers discover it.
Start Here
- Getting Started
- CLI Reference
- How It Works
- MCP Server
- Feature Tiers
- Security
- Contributing
- Latest Release
- npm package
How It Works
- CodeLedger scans the repo for deterministic local signals such as dependency structure, churn, tests, contracts, and task keywords.
- It ranks and packs a bounded set of task-relevant files.
- It writes
.codeledger/active-bundle.mdfor your coding agent. - After work, verification, receipts, and session summaries help show what changed and whether the selected context was useful.
Same task plus same repo state produces the same file ranking behavior.
Core Capabilities
- Give agents the right context: deterministic file selection, scope inference, bounded budgets, blast-radius hints, and co-change context.
- Keep work continuous: session summaries, checkpoints, mid-session refine, and handoff/recovery commands.
- Keep agents inside the task: scope contracts, intent governance, loop detection, and multi-agent conflict checks.
- Prove what happened: review intelligence, receipts, provenance, audit exports, and release evidence.
For the full command surface, see the CLI Reference.
Agent Integration
Claude Code can use CodeLedger hooks after codeledger ready initializes the
repo. Cursor, Codex, GitHub Copilot, Gemini CLI, Aider, Windsurf, and other
agents can read CLAUDE.md plus .codeledger/active-bundle.md, or use the
repo-local wrappers when available.
CodeLedger also includes an MCP server for supported tiers:
codeledger mcp start
codeledger mcp status
See MCP Server and Feature Tiers for setup and tier details.
Trust And Verification
- Runtime source analysis runs locally by default.
- Source code is not sent through CodeLedger telemetry by default.
- No account is required for the local CLI flow.
- Public releases include
SHA256SUMSand release-evidence artifacts. codeledger doctorchecks the local install, hooks, config, index, and ledger health.- The public wrapper, docs, harness, and scanning surface are inspectable in
this repo; the protected hardened runtime is covered by
LICENSE-CORE.
Install
npm install -g @codeledger/cli
codeledger --version
Or use the release zip:
- Download the latest release.
- Extract it.
- Run
install.sh.
The installer uses the bundled package from the zip, so the installed wrapper version matches the release. The wrapper then fetches the matching hardened binary from the GitHub release unless your environment already provides it.
Everyday Flow
cd your-project
codeledger ready
codeledger ready --task "Fix null handling in user service"
Inside an initialized repo, you can also use:
codeledger activate --task "Fix null handling in user service"
codeledger doctor
Browser, cloud, and sandboxed environments can use the repo-local runtime
deployed under .codeledger/bin/ after initialization or vendoring.
Architecture
CodeLedger has an open public surface and a protected hardened runtime:
PUBLIC: CLI wrapper, types, repo scanner, harness, reports, docs, hooks
PROTECTED: Scoring engine, selection algorithm, confidence internals
Use codeledger about, codeledger doctor, and command-specific --explain
output to inspect behavior and evidence without exposing protected
implementation internals.
Privacy
- Installation may use npm and GitHub Releases.
- Runtime analysis runs on your local machine by default.
- Runtime analysis makes zero source-code telemetry calls by default.
- Your source code is not required to leave your machine for the local CLI flow.
- Uninstall at any time.
License
- Public wrapper, types, repo scanning, harness, reports, docs, and examples: MIT
- Downloaded hardened binary: CodeLedger Core License
GitHub may classify the combined licensing structure as "Other" because the repo includes both MIT-covered public files and separately licensed protected runtime terms. Changing the license files should be a human legal decision.
Part Of ContextECF
CodeLedger applies Intelligent Context AI's context-control architecture to software engineering. For enterprise-wide governed context across applications and agents, see ContextECF.
CodeLedger is produced by Intelligent Context AI, Inc. See codeledger.dev.
CodeLedger MCP questions
How do I add CodeLedger MCP to Claude Code?
Run claude mcp add codeledger -- npx -y @codeledger/cli in your terminal. Add --scope user to make it available in every project.
How do I add CodeLedger MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does CodeLedger send my source code to their servers?
No, runtime analysis is local by default and does not send your source code through CodeLedger telemetry by default.
Which AI coding agents are compatible with CodeLedger?
It works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf, and other CLI or MCP-compatible agents.
How does CodeLedger improve coding workflows?
It helps by selecting task-relevant files, which can lead to higher test pass rates, fewer iterations, and reduced token usage.
Do I need an account to use the local CLI?
No account is required for the local CLI flow.