Explore repository history in three views: Overview for recent changes, activity, releases, and health; Records for focused search and filtering; and Timeline for a chronological view grouped by month.
Browse with compact record rows, rounded filter controls, and custom dropdown menus. The desktop sidebar groups record types and deeper filters, while smaller screens keep those controls within reach above the results.
Read the evidence beside a change: its rationale, invariants, verification, files, and linked decisions. Step between records without closing the panel, expand the relationship map when needed, and use the command palette and keyboard shortcuts to navigate.
Use near-white light mode or charcoal/slate dark mode, both with blue accents. The reader follows your system preference until you choose Light or Dark, then remembers that choice across visits.
Meet Ledger's new punched-receipt icon and wordmark. The README now leads with a 24-second recorded tour, a shorter setup path, and examples for supported coding agents.
Try the [live reader](https://kylebegeman.github.io/ledger/) and [public changelog](https://kylebegeman.github.io/ledger/changelog/), rebuilt from the project's records on every push to master. Public releases have direct links and an Atom feed.
ledger stale now searches the files a record's coverage patterns cover. A record that lists src/** or plugins/*/adapter.json beside a few exact files no longer reports the symbols and anchors that live under the pattern as drift: the patterns become Git :(glob) pathspecs searched with git grep. When the search cannot run, because Git is missing or a pathspec is unusable, the pattern reports nothing rather than guessing.
A Changed Files heading that names a directory path, such as ### internal/composer, CHANGELOG.md, now covers the record's files under that directory, so the block's anchors are checked against them. A heading word without a path separator, as in "Tests, skill, and docs", stays prose.
An anchor that names a path the tree still holds, by full path, by a file name under some directory, or as a directory itself, is a reference to that file rather than content to find inside another. A bare file name counts only when its tail looks like an extension, so a member name such as Server.throttle is still checked as a member name.
Together these take the stale report on a 12,000 file repository from 169 signals to 14. The pattern search runs once per record and block file list and only for records that name patterns, so ledger stale and ledger doctor take about 15 seconds on a tree that size, against well under a second where receipts list exact files.
ledger hooks install --host codex --launcher writes Codex hooks that run node .ledger/bin/ledger.mjs, plus that script, which runs your agents.command. Codex approves hooks by their definition, so later installs with a new --command rewrite only the script and Codex keeps the approval. Start Codex at the project root so the hooks find the script. Later installs keep the form the hook file already uses, and --launcher=false switches back and removes the script.
ledger doctor accepts hooks that run the launcher, and warns when the script is missing, runs a different command, or is out of date.
When no tracked file matches git.requireEntryFor, the doctor symbols check names those patterns instead of suggesting the TypeScript parser. When TypeScript sits beside Go, Rust, Python, or Swift, its message says those symbols come from Ledger's outlines and need nothing installed.
ledger new, feedback, backlog new, decision new, and promote take section bodies with --section Heading=text and --sections-file, and the JSON API and MCP take them as sections. ledger new also takes --file, --doc, --symbol, --related, --decision, --backlog, and a docs impact declaration, so one command can write a receipt that passes ledger ready.
ledger update <id> changes a record in place: its title and heading, status, list fields, docs impact, or sections. A list flag replaces that whole list. Over MCP it is ledger_update, which asks the user to confirm first.
The MCP tools that write records now check the call before asking, so the user is never asked to confirm a call that would fail, and the confirmation names the sections a call writes.
ledger context prints one review packet for the working tree, the staged diff, or a --base and --head range. For each changed file it gives coverage, docs impact, and the newest records that mention it with their invariants and conflict rules, and it lists the change's receipts with their verification. It fits a token budget, and it is also the ledger_context MCP tool and an API route.
ledger doctor checks installed Claude Code, Codex, and Cursor hooks. It warns when a hook runs a command other than agents.command, or when that command fails or reports a different Ledger, because hosts skip failing hooks without a message. ledger doctor --fix first repairs interrupted writes, a stale lock or engine record, a stale cache, stale indexes, and a missing reader, and never edits records.
Drafts, hook drafts, and ledger stale read Go, Rust, Python, and Swift declarations, with methods and members named Type.member, or Type::member in Rust. A draft names the method a diff touched rather than the whole type, and ledger doctor says which languages are outlined. No toolchain or new dependency is needed.
In the internal reader, a record's files, patterns, and symbols open a list of every record that names them. Its relationships open the linked records, and a Referenced by list shows the records that link to it. The views have their own URLs and work from a file: URL.
The reader's command palette suggests matching files, symbols, and areas before records. Typing right after opening it keeps every character.
The record panel copies the record's link, its source path, the ledger packet command for it, and its agent-ready context.
Both reader profiles mark records that are new or changed since your last visit and can list only those. The state stays in your browser.
Row and panel summaries read as plain prose, without list or bold markers.
ledger render --profile public also writes feed.xml, an Atom feed of the newest 50 releases, and gives each release a permalink such as #v0.9.2. Both profiles carry a description, Open Graph tags, and an icon. --site-url makes the canonical link and the feed's links absolute. docs/PUBLISHING.md has a GitHub Pages workflow.
docs/COMMANDS.md lists every command's usage, help, and flags, generated from the same registry as ledger help.
The reader's embedded script and stylesheet are minified, and detail chunks are smaller, which offsets the new features' size.
ledger mcp and the engine's /mcp speak MCP 2026-07-28 and the 2025 revisions from the same tools, resources, and prompts. Clients on the 2025 revisions keep working.
New MCP tools write records: ledger_new, ledger_feedback, ledger_backlog_new, ledger_decision_new, ledger_promote, ledger_session_start, ledger_session_note, and ledger_session_close. Each one asks the user to confirm first, naming the action and the project. It writes nothing unless the user accepts with the box checked. A confirmation covers only the exact call it was asked for and expires after ten minutes.
A declined confirmation returns confirmation-declined. A client that cannot show one gets confirmation-unavailable before anything is asked. Neither writes anything.
Over the engine's HTTP endpoint, only 2026-07-28 clients get the write tools, and those tools write only to the engine's own project. 2025-era clients can confirm over ledger mcp when they support elicitation.
On protocol 2026-07-28, the tool, prompt, and template lists carry one-hour cache hints, and the engine notifies subscribed clients when records change.
Ledger depends on @modelcontextprotocol/server and @modelcontextprotocol/node instead of @modelcontextprotocol/sdk, so a production install is 7 packages instead of 94.
createLedgerMcpHttpHandler and serveLedgerMcpStdio join the library's exports. listLedgerMcpTools and the operations contract mark the tools that ask for confirmation.
On /mcp, GET and DELETE now answer 405. Before, GET opened an event stream that never carried a message, and DELETE answered 200 without doing anything.
ledger hooks install --host codex now says where to trust the hooks: /hooks in the Codex CLI, or the Hooks page of the Codex app's settings. It also says to trust them again after the hook commands change, because Codex skips a changed hook until then.
docs/SCHEMA.md lists the product note statuses: captured while follow-ups are open, resolved once they ship.
The static reader and the public changelog use Dossier's visual system in light and dark themes: plum-tinted neutrals, borders in place of shadows, system font stacks with no font requests, and one motion curve. Ledger's emerald accent and mark stay.
Color marks status only. Landed, released, accepted, and shipped records are teal. Drafts, planned, proposed, and in-progress work, active sessions, and captured notes are violet. Blocked and rejected records are coral, and the rest are neutral. Kind badges are neutral outline chips, and superseded, deprecated, and expired records show a neutral dot instead of a red one.
The masthead is shorter, so records start higher on the page. From 1100 pixels wide, the facet rail sits on the left with a label over each group.
The theme toggle cycles Auto, Light, and Dark, shows the current choice, and can return to following the system setting.
Muted text, the search placeholder, and warning text in the light theme now meet 4.5:1 contrast, and text inputs and selects have a 3:1 edge. The record list no longer scrolls sideways at tablet widths.
The search index, its shards, graph.json, and graph/contracts.json are written as compact JSON, and search shards fill up to render.budgets.maxSearchIndexBytes, passing it only when a single record is larger. Before, a shard of long records could exceed the budget and fail ledger doctor.
Hook drafts and ledger new --from-diff list only the symbols a change touched. Each file's anchors are the declarations or the innermost Markdown section that hold a changed line, headings inside fenced code are ignored, and a file whose change sits outside every symbol keeps a TODO anchor. New files still list their symbols, up to twelve.
ledger ci prints each failing file with the reason, not just counts. When a Claude Code, Codex, or Cursor session touched a file that coverage or docs impact reports, ci, coverage, and docs impact name that session and its draft receipt, and say to finish the draft rather than run ledger new. The checks still fail until the receipt is finished, and GitHub annotations leave these hints out. The JSON output of all three commands gains a sessions list.
ledger release <version> --include-unreleased --assign --update adds receipts that landed after a release record was written to its entries and ## Changes, and keeps the summary, public notes, verification, and known issues you wrote. --write still refuses to overwrite a record.
Symbol extraction no longer crashes next to TypeScript 7, which ships no JavaScript API: drafts fall back to the regex extractor, and ledger doctor says why. Installing @typescript/typescript6 beside TypeScript 7 restores parsed symbols, and TypeScript 5.0 to 5.4 now parse too.
The MCP SDK is 1.30.0, zod is 4.6.5, and yaml is 2.9.1, and the composite GitHub Action pins actions/setup-node v7.0.0.
The README gives the measured cost of running hooks through npx, about 0.3 seconds per hook, and how an installed copy avoids it.
Hooks no longer lose edits when an agent changes several files at once. The workspace write lock waits briefly for another Ledger process instead of failing, and a hook whose record changed while it waited re-reads and retries, so every edited path reaches the session record and its draft.
Ledger works from a directory inside a Git repository, such as packages/app/.ledger. Changed paths from Git are made relative to that directory, so hook drafts, coverage, docs impact, verify, and new --from-diff see the project's own files.
A draft the hooks create is always announced on the next prompt, even when it reuses the id of a draft you deleted. ledger cache clear now also removes the notice store, which forgets sessions that no longer exist.
ledger hooks install keeps a command you added to Ledger's own hook group instead of adding a second Ledger group, and ledger agents --write replaces every managed block so a file never carries two versions.
Hook drafts from wide diffs stay readable: the default title names at most three areas, drafts keep the eight most touched areas, and symbols are capped. Codex apply_patch edits sent as an argument list are recorded, and a hook payload without a session id is ignored with a message instead of filed under another session.
Hook and authoring edits keep a record's line endings, so session records on Windows checkouts stay CRLF.
The reader ranks search results exactly as ledger search does; before, it ignored part of each record's text and dropped matches. Opened from disk, the command palette lists and filters records instead of staying empty, and command-click on a record opens it in a new tab.
Inline code in the reader shows a visible chip in the light theme, a summary that is one long code span keeps its text, and code spans are found in linear time.
ledger verify --run matches environment assignments as part of the allowlisted command. A Verification bullet such as LEDGER_UPDATE_CONTRACT=1 npx vitest run runs only when verification.allow lists that assignment, and one that sets NODE_OPTIONS or PATH without a matching pattern is skipped.
Only change entries cover a path. Under git.coverage: any, session records, backlog items, and decisions no longer satisfy coverage, which now matches docs impact, and ledger ci messages no longer say "in this change set" under any. A docsImpact declaration whose reason is still a TODO never counts as evidence, whatever its status. The docs impact JSON field historicalFiles is now earlierEvidenceFiles.
ledger adopt ignores vendor/ at any depth and never makes it a coverage root, ignores build output inside packages, and leaves Make targets and npm scripts that reset, migrate, format, serve, start, or watch out of the proposed allowlist, which lists at most 40 npm scripts.
ledger docs reconcile refuses a routing path it cannot read, such as a directory or symlink, even with --force, and says why.
Under git.coverage: any, an earlier receipt covers a changed file only when it names that file. A pattern such as src/** still covers files from a receipt in the pull request, but one in an old receipt no longer exempts a directory from every later change, for coverage and docs impact alike. ledger coverage and ledger ci report such a file as matched only by patterns in earlier receipts and ask you to name it in a receipt.
The release workflow takes the GitHub Release notes from ledger release notes, and CI regenerates the README's terminal cards on a pinned date and fails when one is out of date.
Agents now hear about the receipt the hooks drafted for them. A new user-prompt-submit hook for Claude Code and Codex names the draft once on the next prompt, and session start lists every receipt the session links, so the agent finishes the draft instead of creating another. Landing a receipt mid-session no longer produces a second draft. Re-run ledger hooks install to add the hook; Codex asks you to approve the hooks again.
agents.command in .ledger/config.yaml sets the one command that runs Ledger in a repository, such as npx ledger or a pinned npx --yes @kylebegeman/ledger@0.8.0. ledger hooks install --command saves it, and the hooks, the AGENTS.md block, the skill, and the context the hooks inject all use it. For Claude Code, --import-agents adds the @AGENTS.md import to CLAUDE.md.
ledger adopt reads the tracked tree and writes a configuration that fits it: coverage roots for the tracked top-level directories, ignores for generated code such as templ and sqlc output, a proposed verification.allow from the detected toolchain with release and deploy targets left out, and git.coverage: any. ledger init and ledger adopt also add a marked block to .gitignore for Ledger's derived files.
ledger docs reconcile no longer overwrites routing files Ledger did not generate. It explains the refusal and exits 1 unless --force is passed, and ledger adopt points docs.routing under .ledger/ when curated routing files exist. A START_HERE.md from an older init that never ran reconcile needs --force once.
ledger session prune --write keeps expired sessions that another record links and closes them instead of deleting them; session records are meant to be committed. An active session past its expiry, such as a Claude desktop tab closed with /exit, stops collecting edits, and the next session keeps its linked receipts.
Hook drafts no longer list session records or templates, start with a neutral Changes to <areas> title that ledger ready asks the agent to replace, and record edits Codex makes with apply_patch.
Hooks no longer draft a duplicate of a receipt you wrote yourself. A receipt that is new or modified in the working tree covers its files like one the session links, a link named in either record counts, and only touched files that still differ from HEAD are pending, so a receipt written with ledger new or already committed is respected.
ledger verify --run understands agents.command. A Verification command written with it, such as npx ledger validate or a pinned npx --yes @kylebegeman/ledger@0.8.0 ready, matches the same ledger pattern in verification.allow, and a bare ledger command runs through the configured command instead of whatever ledger is on the PATH.
Docs impact follows git.coverage. Under any, a changed source file can take its evidence from an earlier receipt that lists it with a reviewed docsImpact declaration or docs references, so ledger ci judges coverage and docs impact under one mode, and adopted repositories stop failing on files their receipts already cover. The docs impact output lists those files under historicalFiles. Repositories on current see no change.
With comment: "true", the GitHub Action keeps one Ledger comment on a pull request and updates it on later runs instead of posting a new one. Pull requests from forks get a notice instead of a failed step, and a failed GitHub API call is a warning.
The reader renders Markdown code spans in summaries, invariants, verification, and release notes as inline code instead of showing backticks. Record text is escaped first, so a code span never becomes markup.
ledger stale and ledger doctor no longer fail when a receipt lists a screenshot or another file that is not UTF-8 text; anchors and symbols are checked against the text files it lists.
The reader no longer logs an InvalidStateError in the browser console when the browser skips a view transition, as it does in a background tab; the list still updates.
ledger doctor no longer asks for the TypeScript parser in repositories with no TypeScript or JavaScript under coverage.
The README shows the reader, the context agents receive, and the checks with real command output. Ledger has a new emerald mark, and the reader's accent color follows it.
Coverage is now bound to the change set. Under the new default git.coverage: current, a changed source file must be listed by a change entry that is itself part of the pull request or working tree; files covered only by older records are reported as historical. Set git.coverage: any or pass ledger coverage --mode any while adopting Ledger on a repository with history.
Docs impact is judged per source file: each changed file needs a change entry in the same change set that lists it and declares docs impact or references docs. A docs edit elsewhere no longer clears every file.
ledger verify --run executes the backticked commands in change entries' Verification sections that match verification.allow, and records command, exit status, duration, and commit in .ledger/reports/evidence.json. doctor, stale, explain, packet, and the reader show whether evidence is fresh, stale, or failed.
ledger stale checks Changed Files anchors and the invariants that cite them against the current code, reporting stale-anchor and stale-invariant. Write anchors in backticks; ledger new --from-diff now drafts them that way.
ledger ci --github prints pull request annotations and a job summary, and the repository's composite action runs it: uses: kylebegeman/ledger@v0.7.0.
createLedgerClient and connectLedgerClient give TypeScript callers a client for ledger serve --api whose operation names and inputs are checked at compile time against the registry.
The reader's browser runtime is now a typed module bundled with esbuild and tested in a browser environment. Large catalogs shard the search index, split the graph, and move record details into lazily loaded chunks when the page would exceed its budget; small catalogs keep working fully offline.
ledger search --full-text narrows candidates with sqlite FTS5 on large catalogs. Default search is unchanged and identical on every cache backend.
Symbol extraction reports which extractor ran. typescript is an optional peer dependency: install it for parser-backed anchors, otherwise a regex fallback runs and ledger new and ledger doctor say so.
ledger hooks install --host claude-code|codex|cursor installs lifecycle hooks into the host's project hook file. A session starts with a budgeted Ledger packet, every edit is recorded on a session record, stop drafts a change entry from the touched paths and the Git diff, and pre-compaction writes a handoff so the next context window keeps the same memory. Nothing auto-starts the engine.
ledger skills install writes .agents/skills/ledger/SKILL.md (with a .claude/skills/ledger link for Claude Code) so skills-aware agents know when to call packet, explain, session note, new, promote, and ready. ledger agents --write maintains the same workflow as a fenced block in AGENTS.md.
Session records: a new short-lived session kind under .ledger/sessions/ with ledger scratch, session start|touch|note|close|prune, a configurable expiry (sessions.expiresInDays, default 7), an expired-session stale signal, and promotion into a change entry with ledger promote S000N.
ledger ready distinguishes a valid draft from one ready to land: TODO markers, template placeholders, empty sections, missing Verification or Invariants bullets, unreviewed docs impact, and missing references are reported with line numbers, and the command exits 1.
Authoring commands: ledger backlog new, ledger decision new, ledger promote <id> (carries acceptance checks into Verification and updates the item in one transaction), and ledger release notes <version> (prints a record's Public Notes). Backlog and decision id widths are configurable (ids.backlogWidth, ids.decisionWidth).
Library: createBacklogItem, createDecision, promoteRecord, readReleaseNotes, draftChangeEntry, session helpers, checkReadiness, hook and skill installers, and frontmatter editing helpers are exported from the package root; ledger_ready and ledger_release_notes join the MCP tools.
ledger serve --api starts the engine: the reader plus a JSON API at /api/v1 (every workspace operation as POST /api/v1/operations/<name> with the same machine envelope as --json and the exit code in a Ledger-Exit-Code header), a server-sent event stream at /events, MCP over Streamable HTTP at /mcp, and a server card at /.well-known/mcp/server-card.json. The same loopback and token hardening as ledger serve applies.
While the engine runs, CLI commands in the same project delegate to it and answer from its warm cache with identical output and exit codes. Pass --local or set LEDGER_NO_DAEMON=1 to run in-process; a stale or missing engine falls back automatically. ledger doctor reports the engine state.
The reader reloads itself after every rebuild when served by the engine and keeps its URL state; a failed rebuild keeps the last good render.
MCP hosts get resources (ledger://records/{id}, ledger://packet/{path}, ledger://contract) and prompts (ledger_agent_instructions, ledger_handoff) over both stdio and HTTP.
Search scoring lives once and is shared by ledger search and the reader, so terminal and browser rankings match exactly.
Recursive watching survives Windows short-name paths.
Every command except serve and mcp now supports --json and returns the versioned machine envelope, including init, new, feedback, index, agents, and the docs subcommands.
The MCP server grew from 8 tools to 18, each with input and output schemas, read-only annotations, and structured content. The original 8 keep their names, inputs, and summaries.
Repeated commands and agent calls parse only the records that changed. A catalog cache under .ledger/cache/ (JSON everywhere, built-in sqlite on Node 24.15 or newer) cut warm reads on this repository from 38 ms to 4 ms. New commands: ledger cache status, ledger cache warm, ledger cache clear.
ledger explain, ledger conflict, and ledger packet agree on which records match a path and now include the decisions, backlog items, and superseding records one hop away. Packets carry related records within the token budget, and graph.json gains supersedes edges.
ledger doctor fails, rather than warns, when the rendered reader is over its size budget.
Library: ledgerOperations, buildOperationsContract, retrieveByPath, matchFilePath, and relatedRecords are exported from the package root; explain JSON data now carries records, related, and missing.
The static reader and its search index now list records newest-first on both the internal and public profiles, and the command palette shows the most recent records.
Tests pass on Windows as well as macOS and Linux.
The roadmap gains Phase 11, the local memory engine direction, and records which earlier proposals were retired.
Tagged releases publish to npm through trusted publishing and create a GitHub Release from the release record. Homebrew instructions were removed until a tap exists, and development now happens through pull requests into master.
Release records now require a Public Notes section, and the internal render total budget is 2,500,000 bytes.