CodeLedger

What problem are we solving?

The Problem — AI coding agents waste 40–60% of their context window on irrelevant files. Every session starts cold. Institutional knowledge lives in people's heads and disappears when they leave. There is no risk signal before a merge.

The Solution — CodeLedger is a deterministic context control plane for software development. It scores every file in a repository, selects only what the current task requires, captures outcomes, and promotes successful patterns into reusable institutional memory.

The Intelligence Layer — The Task Intelligence Engine does not start from zero. It is seeded from day one with a curated ontology pack of golden patterns — distilled from peer organizations and leading engineering teams at organizations including Google, SAP, and Salesforce. As your team uses CodeLedger, your own earned patterns layer on top, making the system progressively more tailored to your codebase, your conventions, and your standards.

The Principle — No cloud. No training pipeline. No behavior change required. Engineering management installs it once. Every developer and every AI agent benefits automatically — from collective intelligence on day one, and from your own institutional memory from day two onward.

Logs are history. Ledger is intelligence.

CodeLedger turns every coding action into a persistent, compounding asset.

Without CodeLedger:

• Context is lost between agents
• Every task starts from scratch
• Failures repeat

With CodeLedger:

• Context persists across sessions and agents
• Success patterns compound
• Engineering becomes measurable and auditable

This is not another AI tool. This is a Context Control Plane for your repo.

Works with: Claude Code | Cursor | Codex | GitHub Copilot | Gemini CLI | Any CLI-based agent

What happens when you use CodeLedger?

1. You run a task
2. CodeLedger selects context deterministically
3. The outcome is recorded
4. Future tasks improve automatically

Over time, your repo builds its own intelligence layer.

The Two-Loop Model

CodeLedger helps in two ways:

⚡ Now — Assembles the minimal context needed for your current task. Fewer irrelevant files, fewer retries, faster execution.

💎 Next — Captures what worked and builds reusable memory so future tasks start smarter. Successful patterns compound into institutional knowledge.

⚡ Now                          💎 Next
Select context → Execute →      Record evidence → Promote patterns →
                                Future tasks start smarter

AI Agent Integration (MCP)

CodeLedger includes an MCP server that gives Claude, Cursor, and Windsurf direct access to your repo's memory:

codeledger mcp start     # Launch MCP server (stdio transport)
codeledger mcp status    # Check readiness + connection instructions

Tools available to agents:

• query_ledger — Search for verified patterns before coding
• get_active_context — Get the task-specific context bundle
• record_interaction — Report outcomes for memory compounding

MCP integration requires Team or Enterprise tier. See Feature Tiers.

Engineering Dashboard

Generate a repo-local engineering dashboard from your Context Ledger:

codeledger dashboard build    # Generate static HTML dashboard
codeledger dashboard open     # Open in browser (no server needed)

The dashboard shows: system health, integrity signals, quality metrics, pattern reuse intelligence, and estimated engineering value — all derived from real execution evidence.

Full dashboard requires Team or Enterprise tier. Individual tier receives a placeholder with teaser stats.

Semantic Merge Verification

Prevent silent merge failures where code compiles but types or config are semantically broken:

codeledger merge-check --save-baseline    # Before parallel work
codeledger merge-check --verify           # After pulling a merge
codeledger merge-check                    # Quick health check

Catches removed types with active importers, config fields accessed but missing from defaults, and name collisions across packages.

Feature Tiers

codeledger features           # See what's available at your tier
codeledger upgrade            # Explore Team / Enterprise

Why this matters

CodeLedger is built on a local-first Context Ledger:

• Append-only memory of engineering activity
• Outcome-linked learning (what worked vs what failed)
• Cross-agent continuity
• Deterministic context selection

Your repo becomes an evolving system — not just code.

Get CodeLedger

Download Latest Release · npm install -g @codeledger/cli · Getting Started Guide · CLI Command Reference

npm install -g @codeledger/cli   # or download the zip from Releases
cd your-project
codeledger ready
git add .codeledger/bin/ .gitignore
git commit -m "chore: init codeledger"
./.codeledger/bin/codeledger task --task "Fix null handling in user service"
codeledger task --task "Fix null handling in user service"
# Your agent now has .codeledger/active-bundle.md with the right context

Your agent reads the right files first. Every time.

For browser/cloud sessions, the committed .codeledger/bin/ runtime package is what gets executed. codeledger ready initializes the repo, scans it, and deploys the canonical standalone build so the checked-in runtime matches the version you tested locally. Inside a vendored repo, ./.codeledger/bin/codeledger <command> is the easiest interactive entry point.

Truth Control Plane

Once a repo is initialized, CodeLedger can reconcile reality across drift, outcomes, snapshots, handoffs, and release state:

codeledger drift --history --verify-integrity
codeledger outcome --json --verify-integrity
codeledger harvest --preview --verify-integrity
codeledger context-handoff --target codex --verify-integrity
codeledger snapshot --verify-integrity
codeledger time-travel --to <snapshot-id> --verify-integrity
codeledger reality-check --verify-integrity

These commands extend CodeLedger's existing verification and memory systems. They do not create a separate ledger or memory store.

What Happens After Install

Installing CodeLedger gives you the CLI. To use it in a project, initialize that project:

codeledger init

That sets up CodeLedger inside the repo by creating:

• .codeledger/ for project-local cache, bundles, sessions, and runtime data
• .codeledger/bin/ for the vendored standalone runtime
• .claude/hooks.json for automatic integration
• updates to CLAUDE.md so agents know how to use the context bundle

Your normal flow after install is:

1. Install CodeLedger

npm install -g @codeledger/cli

2. Go to your project

cd your-project

3. Initialize and scan CodeLedger in that repo

codeledger ready

4. Commit the vendored runtime if you want browser/cloud support

git add .codeledger/bin/ .gitignore
git commit -m "chore: initialize codeledger"

5. Start using it

codeledger ready --task "your task here"

🌐 Beyond CodeLedger

CodeLedger is just the beginning.

It’s built on ContextECF — a broader context infrastructure approach for making AI systems deterministic, auditable, and cumulative instead of probabilistic and forgetful.

At the core is a simple idea:

Every interaction with AI should make the system smarter, more reliable, and more accountable over time.

🧠 What This Means (In Practice)

While you’re using CodeLedger for development, the same foundation extends to:

• 🧑‍💻 Engineering → Shared memory across agents, verified execution, no rework
• 📊 Decision-making → Faster, context-rich executive decisions
• 🗂️ Knowledge → Institutional memory that doesn’t disappear
• 🤖 AI agents → Coordinated, governed, and trustworthy systems
• 💬 Communication → Smarter meetings, better alignment
• 📈 Revenue → Relationship intelligence and proactive insights
• 🔐 Governance → Built-in auditability and compliance

🚀 Why It Matters

Most AI tools:

• Recompute context every time
• Lose what they learned
• Can’t prove what happened

ContextECF + CodeLedger:

• Remember
• Verify
• Compound value over time

What you’re building isn’t just output.

You’re building a long-term context asset for yourself — and potentially your entire organization.

🤝 Share This

If CodeLedger is helping you, it’s worth a quick share with:

• CTO / VP Engineering
• Platform / DevEx teams
• AI / Data leaders

🏢 About

Intelligent Context AI Inc is the creator of CodeLedger and ContextECF.

If your team is exploring AI at scale, agent systems, or enterprise context management:

📩 customersuccess@intelligentcontext.ai
📞 916-753-7432

CodeLedger helps you capture truth in code.
ContextECF helps you scale that truth across the enterprise.

Important:

• You do not need to keep a separate CodeLedger folder elsewhere on your machine.
• The long-lived project state lives inside each repo in .codeledger/.
• The global install is just the CLI entry point.
• For browser/cloud environments, the committed .codeledger/bin/ runtime is what makes CodeLedger portable.

Why CodeLedger?

AI coding agents are powerful, but on real codebases they waste time, tokens, and accuracy because they lack targeted context. CodeLedger fixes that — deterministically.

No embeddings. No cloud. No telemetry. Fully local at runtime. Fully deterministic.

Install

# Recommended: install globally
npm install -g @codeledger/cli

# Or use without installing
npx @codeledger/cli --version

# Or install as a dev dependency
npm install --save-dev @codeledger/cli

Verify it works:

codeledger --version

See GETTING-STARTED.md for the full 5-step setup guide, configuration, and troubleshooting. For a command-by-command walkthrough with example output, see docs/CLI_COMMAND_REFERENCE.md.

Alternative: Download from GitHub Releases

Download the latest release — extract the zip, then drag install.sh into your terminal and press Enter. 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.

Best For

Rule of thumb: If your agent regularly reads more than 25 files before making its first edit, CodeLedger will help.

How It Works

1. Scans your repo (dependency graph, git churn, test mappings, content index)
2. Scores every file across 10 weighted signals
3. Selects the most relevant files within a token budget
4. Delivers a context bundle your agent reads immediately

Same task + same repo state = same file rankings and content. Every time.

See SCORING.md for details on how files are scored.

Installation Note

After a new release, npm install -g @codeledger/cli automatically fetches the hardened platform binary from GitHub Releases. For the first ~10 minutes following a release, the binary may still be uploading. The installer retries automatically with backoff — this is expected behavior, not an error.

If you see "Binary pending" messages during install, simply wait. The installer handles the timing automatically and will complete within a few minutes.

Quick Start

cd your-project
codeledger init

That's it. Start your agent and describe your task in plain English. The hooks will:

1. Extract your intent and scan the repo automatically
2. Score every file across multiple weighted signals
3. Select the most relevant files within a token budget
4. Write a context bundle for your agent to read

No commands to memorize. Context is ready when your agent starts.

Inside an initialized repo, prefer:

./.codeledger/bin/codeledger <command>

That repo-local wrapper prefers a newer global codeledger install on your machine and falls back to the vendored standalone runtime in browser, CI, and container environments.

Agent Integration

Claude Code (Zero Setup)

CodeLedger ships with Claude Code hooks. Just run codeledger init and start Claude Code — init warms the repo index, and the SessionStart hook handles activation automatically.

No commands to remember. Context is ready when your agent starts.

See examples/claude-code-hooks.json for the hook configuration.

Cursor / Codex / Other Agents

After codeledger init, your agent reads the CLAUDE.md instructions and .codeledger/active-bundle.md for context. Hook-aware environments refresh automatically for new meaningful tasks. In local non-hook environments, the repo-local ambient wrappers now apply the same rule before handoff:

./.codeledger/bin/codex "your new task"
./.codeledger/bin/claude "your new task"

Acknowledgement-only follow-ups like Yes please do not refresh context. If you need to trigger the rule directly, use:

./.codeledger/bin/codeledger auto-refresh --prompt "your new task"

For plugin-first, mid-session retrieval, ask CodeLedger for refreshed context before using raw search:

./.codeledger/bin/codeledger broker refresh --task "implement the related feature" --json

That returns the active bundle, top-ranked files, and bundle delta for the task shift. Use rg or manual file search only if the broker result is insufficient. Human-readable broker output also includes matched runtime patterns with ranking reasons like lifecycle status, confidence, reuse count, promotion state, merge count, and the most recent promotion rationale.

For session-aware inspection during the same run:

./.codeledger/bin/codeledger broker current --json
./.codeledger/bin/codeledger broker timeline --limit 10 --json

codeledger scan ends with a compact executive summary, grouped policy recommendations, and suggested next commands. Use codeledger scan --full-policy when you want the full override list instead of the compact default view. codeledger memory patterns shows promoted runtime patterns along with trust basis and promotion state for quick inspection.

For relevance-managed architectural memory:

codeledger memory status
codeledger memory explain --id <artifact-id>
codeledger memory inject --task "Fix auth regression" --paths "src/auth/login.ts"
codeledger memory compact --dry-run
codeledger memory prune --dry-run

Policy memory is stored under .codeledger/memory/policy-artifacts.json and keeps HOT/WARM/COLD/ARCHIVED artifacts deterministic, compact, and auditable. codeledger memory inject builds the bounded task-start injection bundle that sits on top of DRS: HOT is eligible, not automatically injected.

Task-start injection is driven by a deterministic taxonomy classifier. Before injection, CodeLedger classifies the task into one primary type such as bug_fix, auth_change, migration, infra_change, dependency_change, api_change, ui_change, docs_only, or unknown. It also emits secondary tags like high_risk, shared_core, auth_sensitive, schema_sensitive, customer_visible, and incident_related, plus a confidence score, risk level, complexity, and evidence trace.

If you need repo-specific tuning, add .codeledger/taxonomy.yaml:

overrides:
  paths:
    "services/legacy/**":
      boost:
        refactor: 0.5
      add_tags:
        - high_risk
  keywords:
    "decommission":
      set_type: migration
      weight: 1.5

This lets you bias classification deterministically without changing the global defaults.

CLI Commands

# ── Getting Started ───────────────────────────────────────────
codeledger init [--force]                # Set up .codeledger/ with config and scenarios
codeledger doctor                        # Integration health check (config, hooks, index, ledger)

# ── Context Selection (daily use) ─────────────────────────────
codeledger scan                          # Build repo index (dep graph, churn, test map)
codeledger bundle --task "…"             # Generate a deterministic context bundle
  --scope "src/auth/,src/api/"           #   Restrict to path prefixes (monorepo-friendly)
  --near-misses                          #   Show files that almost made the cut
  --blast-radius                         #   Annotate dependents and impacted tests
  --explain                              #   Dump per-file scoring breakdown
  --expand                               #   Double the token budget
  --layer-order                          #   Sort files by architectural layer
codeledger activate --task "…"           # Scan-if-stale + bundle + write active-bundle.md
  --scope --branch-aware                 #   Same flags as bundle, plus branch awareness
  --near-misses --blast-radius --explain #   All diagnostic flags supported
codeledger refine --learned "…"          # Re-score with new context mid-session
  --drop "file1.ts,file2.ts"             #   Remove specific files
  --add-keywords "pool,cache"            #   Inject new search terms

Command-driven activation is now deterministic:
- CodeLedger now uses a single ambient activation policy table for task-bearing commands
- pre-refresh commands such as `codeledger context --task "..."`, `codeledger broker refresh --task "..."`, `codeledger memory inject --task "..."`, `codeledger complete-check --task "..."`, and `codeledger audit --task "..."` establish or refresh task context in the background before they run
- command-managed commands such as `codeledger task`, `codeledger codex`, `codeledger claude`, `codeledger preflight`, `codeledger bundle`, `codeledger manifest`, `codeledger verify`, and `codeledger activate` establish task context themselves, so the CLI avoids duplicate activation in the same invocation
- help, version, and status-style commands do not trigger ambient activation
- `codeledger activate --task "..."` remains the explicit/manual fallback and power-user entrypoint

GitHub Copilot support is available through the existing generic task runtime:
- `codeledger task --agent copilot --agent-bin "<copilot-compatible command>" --task "..."`
- for GitHub-hosted Copilot coding agent sessions, use CodeLedger to prepare and verify context around the agent with `bundle` and `verify`

Multi-agent repo coordination is now repo-native:
- `codeledger claim <paths...>` records active file or directory claims before edits happen
- `codeledger preflight-edit <path>` checks a target path against active claims and policy before you modify it
- `codeledger leases`, `codeledger release`, and `codeledger coordination` expose active leases, stale claims, and overlap summaries
- validation records bind decisions to commit hash, repo fingerprint, session ID, and claimed scopes

Product promise:
- Git tells you after two agents collided. CodeLedger tells you before they do.

# ── Session Management ────────────────────────────────────────
codeledger session-init                  # Initialize a new session (returns session ID)
codeledger sessions                      # List active sessions and file overlaps
codeledger session-progress              # Write ground-truth progress snapshot
codeledger session-summary               # Show session-end recall/precision metrics
codeledger session-cleanup               # Clean up a session's state files
codeledger checkpoint create             # Save work-in-progress snapshot
codeledger checkpoint restore --id …    # Resume from a checkpoint
codeledger checkpoint list               # List available checkpoints
codeledger shared-summary                # Cross-session coordination summary

# ── Intent Governance ─────────────────────────────────────────
codeledger intent init --objective "…"   # Create a structured task contract
codeledger intent show                   # Display drift score and per-field distances
codeledger intent set --objective "…"    # Update contract fields mid-session
codeledger intent ack                    # Acknowledge drift (reset or accept)

# ── CI / Enterprise Governance ────────────────────────────────
codeledger setup-ci                      # Generate CI workflow + policy file
  --provider github|gitlab|circleci|azure #  CI provider (default: github)
  --mode observe|warn|block              #   Set enforcement level (default: warn)
  --output <dir>                         #   Custom workflow directory
codeledger manifest --task "…"           # Generate deterministic context manifest
codeledger sign-manifest --in … --out …  # Sign a manifest with HMAC-SHA256
codeledger policy --print                # Show resolved policy for current repo
codeledger verify --task "…"             # CI enforcement: evaluate policy, emit artifacts
  --explain                              #   Show richer reasoning and repo-standard examples
  --json                                 #   Machine-readable output for CI/AI agents
  --invariant <name>                     #   Narrow to one invariant module

# ── API Server & Compliance ──────────────────────────────────
codeledger serve                         # Start HTTP API server (default: port 7400)
  --port 7400                            #   GET /health, /drift, /outcome, /reality-check, /metrics, /provenance, /policy
                                         #   GET /architecture-health/*, /broker/timeline, /broker/current
                                         #   POST /verify, /bundle, /harvest, /snapshot, /time-travel, /context-handoff
                                         #   POST /broker/resolve, /broker/validation, /broker/neighborhood,
                                         #        /broker/evidence, /broker/completion, /broker/preamble, /broker/refresh
                                         #   Use `codeledger serve --help` for the full endpoint list
codeledger audit-export                  # Export ledger to JSON, CSV, or JSON Lines
  --format json|csv|jsonl                #   SIEM-compatible output
  --output <path>                        #   Write to file (default: stdout)
  --table runs|events|bundles|coverage   #   Filter to one table
  --raw                                  #   Opt into privileged raw export; default output is sanitized
codeledger provenance trace --task "…"   # Trace provenance for one task
codeledger provenance export --json      # Export provenance graph (sanitized by default)

# ── Cowork (Knowledge Mode) ──────────────────────────────────
codeledger cowork-start --intent "…"     # Scan workspace + generate context bundle
codeledger cowork-refresh --intent "…"   # Re-run selection with updated intent
codeledger cowork-snapshot               # Write progress snapshot for continuity
codeledger cowork-stop                   # Finalize session + print summary

# ── Benchmarking ──────────────────────────────────────────────
codeledger run --scenario …              # Execute a single benchmark scenario
codeledger compare --scenario …          # A/B comparison: with vs without CodeLedger
codeledger share [--format twitter]      # Generate shareable result snippet
codeledger clean                         # Remove orphaned worktrees

Benchmark Results

Example results from a mid-sized Node.js service.

Selector Quality (CI-Enforced)

How the Scoring Works

CodeLedger uses a multi-stage candidate pipeline and a ten-signal scorer:

Candidate Generation: Multi-stage pipeline combining keyword analysis, graph traversal, test pairing, and git history signals.

Scoring: Deterministic weighted combination of positive and negative signals, configurable in .codeledger/config.json.

Post-Selection Enrichment:

• Confidence assessment with actionable suggestions
• Pattern exemplars for creation-intent tasks
• Near-miss explanation with budget gap analysis
• Blast radius annotation with impacted test discovery
• Architectural layer ordering
• TODO/FIXME marker surfacing
• Task-type inference (bug fix, feature, refactor, test, config)
• Scope contract derivation (bundle files + dependency neighbors)
• Commit-aware invalidation (addressed files marked as stale)
• Shadow file annotations (temporal co-commit companions with boost reasons)
• Intent drift scoring (objective/scope/constraint change detection)

Run codeledger bundle --task "…" --explain to see the per-file scoring breakdown.

See docs/SCORING.md for the full scoring algorithm documentation.

Review Intelligence

codeledger verify includes Review Intelligence — a repository-aware architectural verification layer that catches risks linters and SAST tools miss. Runs automatically with zero configuration:

• Runtime validation — catches typed routes without runtime input validation (P1)
• Outbound I/O safety — flags HTTP calls without timeouts (P1)
• Repository drift — detects bypass of sanctioned helpers/wrappers (P2)
• Repo-standard discovery — automatically finds and recommends helpers already used in your repo
• AI repair loop — structured JSON output lets AI agents patch and re-verify

Findings support baselines (--update-baseline), inline suppressions (// codeledger: ignore <rule>), and dispositions (new/baselined/suppressed). CI blocks only on new P0/P1 findings.

Agent Governance

CodeLedger extends beyond context selection into deterministic agent governance — three containment layers that keep agents productive without requiring LLM judgment:

Context Containment — what the agent sees:

• Deterministic scoring, bounded budgets, intent-tracked bundles

Execution Containment — what the agent does:

• Scope contracts prevent out-of-scope edits
• Loop detection catches stuck agents before they waste tokens
• Cross-session conflict zones prevent concurrent agents from colliding
• Intent drift scoring flags when the task objective has changed

Quality Containment — what the agent produces:

• Commit-aware invalidation prevents re-review parroting
• Checkpoint bundles enable resume after interruption
• Multi-agent shared summaries give orchestrators full visibility

All governance features are deterministic — numeric thresholds, pattern matching, and set distance calculations. No LLM reasoning. No probabilistic language. Fully auditable.

Architecture: Open Surface, Closed Engine

┌──────────────────────────────────────────────────────┐
│  PUBLIC (MIT License)                                │
│  CLI · Types · Repo Scanner · Harness · Report       │
│  Hooks · Config · Scenarios · Quality Tests          │
├──────────────────────────────────────────────────────┤
│  PROTECTED (CodeLedger Core License)                 │
│  Scoring Engine · Selection Algorithm · Confidence   │
│  Shipped as a single compiled JS binary (~19KB)      │
│  No network calls · No telemetry · Fully local       │
└──────────────────────────────────────────────────────┘

The CLI wrapper, benchmarking harness, types, and repo scanning are fully open — inspect them, contribute improvements, build trust. The scoring algorithm is compiled into a single binary to protect the IP while keeping everything local and transparent in behavior.

# Transparency flags — see what the engine does, not how
codeledger-core --version
codeledger-core --license
codeledger-core --explain-architecture

Share Your Results

codeledger share                        # Markdown summary
codeledger share --format twitter       # Copy-pasteable tweet
codeledger share --format linkedin      # LinkedIn post
codeledger share --clipboard            # Copy to clipboard

Privacy

• Installation requires npm access to fetch @codeledger/* dependencies (one-time)
• After install, runs entirely on your local machine
• Makes zero network calls at runtime
• Collects zero telemetry
• Your source code never leaves your machine
• No account required
• Uninstall at any time

Contributing

The scoring engine is closed, but there are many ways to contribute:

• Bug reports — file issues with reproduction steps
• Feature requests — propose new CLI commands, output formats, or agent integrations
• Documentation — improve guides, examples, and troubleshooting
• Benchmark scenarios — suggest new task/repo combinations for testing
• Agent adapters — add support for new AI coding tools

See CONTRIBUTING.md for details.

Prerequisites

Tiers

Start free. Tier up when your team — or your compliance team — needs more.

License

• Plugin (CLI, types, repo, harness, report): MIT
• Scoring engine (core-engine binary): CodeLedger Core License — free for individuals and OSS, commercial use requires a license

Links

• Getting Started Guide
• Scoring Algorithm
• Changelog
• CodeLedger
• npm: @codeledger/cli
• ContextECF Enterprise

Philosophy

Large context windows are not the answer.

Smarter context selection is.

_{CodeLedger is produced by Intelligent Context AI, Inc. timetocontext.co · codeledger.dev}