Horizon Ledger

A local-first, Git-native decision ledger and workspace for humans and AI agents. Built and iterated by Codex.

Horizon Ledger is a small, composable primitive for AI-assisted engineering: not another note app, but a structured, Git-native ledger of decisions that can be read by humans, CI, and coding agents.

It answers questions that ADRs and commit logs usually fail to answer over time:

• Why was this chosen?

• What alternatives were rejected?

• What evidence supports the decision?

• What changed since then?

• What should an agent know before modifying this file?

Why it exists

Most "why" knowledge dies in three places:

1. ADRs that are separate from code and never maintained.

2. PR descriptions that are unsearchable and hard to connect to other decisions.

3. Slack threads that disappear or lose context.

Horizon Ledger keeps decisions close to code, in Markdown + structured front matter, with explicit evidence, provenance, and graph links.

Related MCP server: LOOM

Install

Install the latest tagged Git release:

bun add github:TTAWDTT/horizon-ledger#v0.27.0

or

npm install github:TTAWDTT/horizon-ledger#v0.27.0

Quickstart

horizon init --mcp
horizon add --title "Use SQLite for local storage" --summary "SQLite is simple and portable."
horizon list
horizon show D-0001
horizon update D-0001 --status decided
horizon evidence D-0001 --type link --value https://sqlite.org --note "SQLite docs" --strength strong
horizon seal D-0001 E-001
horizon search sqlite
horizon why sqlite
horizon scope src/core
horizon score
horizon validate
horizon graph
horizon import-adr docs/adr --dry-run
horizon context src/core
horizon pr-context --base main --head HEAD
horizon trace --base main --head HEAD
horizon gate --base main --head HEAD
horizon export --format markdown --out DECISIONS.md

horizon doctor
horizon web

Change gate

See docs/POLICY.md for opt-in decision policies.

Commit trace and attribution

Horizon can connect implementation history to decisions instead of treating any commit hash as proof:

horizon trace --base v0.25.0 --head HEAD
horizon trace --base main --head HEAD --decision D-0001 --format json

The trace classifies a commit as evidence when its SHA is attached, reference when the commit message names the decision, and scope when it touches the decision scope. The read-only horizon_trace MCP tool exposes the same result to agents. In a monorepo, use horizon workspace trace to preserve root provenance.

Use requireEvidence: attributed when a policy must be enforced by an implementation commit:

policy:
  mode: block
  requireEvidence: attributed

This accepts a commit that touches the decision scope or names the decision in its message. It still treats Git history as immutable local evidence; it does not fetch from a remote or invent proof.

Multi-root workspaces

See docs/PACKS.md for the deterministic pack format.

horizon workspace init
horizon workspace add ../another-repo --name another-repo
horizon workspace list
horizon workspace disable ../another-repo
horizon workspace enable ../another-repo
horizon workspace remove ../another-repo
horizon workspace get D-0001
horizon workspace validate
horizon workspace audit
horizon workspace pr-context --base main --head HEAD
horizon workspace gate --base main --head HEAD
horizon workspace export --format markdown --out WORKSPACE.md
horizon workspace pack export --out WORKSPACE-PACK.json
horizon workspace pack import WORKSPACE-PACK.json
horizon workspace context storage
horizon workspace trace --base main --head HEAD

horizon workspace evidence export --out EVIDENCE-PACK.json
horizon workspace evidence verify EVIDENCE-PACK.json --expect-verdict pass

horizon workspace release export --base main --head HEAD --out RELEASE-AUDIT.json
horizon workspace release inspect RELEASE-AUDIT.json
horizon workspace release verify RELEASE-AUDIT.json --expect-verdict pass

The MCP server also exposes read-only horizon_workspace_list, horizon_workspace_audit, horizon_workspace_context, horizon_workspace_validate, horizon_workspace_gate, horizon_workspace_trace, horizon_workspace_pack_export, horizon_workspace_pack_import_plan, horizon_workspace_evidence_export, horizon_workspace_evidence_verify, horizon_workspace_release_export, horizon_workspace_release_inspect, and horizon_workspace_release_verify tools, so coding agents can query cross-root decisions without a cloud service. Workspace packs, evidence packages, and release audits are deterministic and SHA-256-bound, so you can review, archive, or hand off decisions without a cloud service. Pack import defaults to a read-only plan; add --write to apply it. Workspace configs are validated strictly: duplicate IDs, names, and aliases fail fast instead of silently degrading into a partial graph.

To run a local decision dashboard:

horizon web --port 4173

Then open http://127.0.0.1:4173. The viewer includes:

• a status and quality board

• alternatives, evidence, links, scope, tags, and diagnostics

• a local decision/evidence graph

• search over decisions, evidence, alternatives, and scope

The viewer is served on 127.0.0.1, uses no remote assets, and reads from the Git-native files on every request.

To expose the ledger to an MCP-compatible coding agent:

horizon mcp

Read-only is the default. To allow decision capture, use horizon mcp --write.

What you get

• local-first, Git-friendly Markdown decisions

• structured alternatives, evidence, provenance, and optional sha256 seals

• graph, search, scoring, cross-repository workspaces, and portable packs

• a local-only human dashboard with no telemetry

• optional sha256 evidence seals, commit attribution, hash-bound gate reports, SARIF output, and portable evidence packages

• useful for humans, coding agents, and opt-in CI gates

• no vendor lock-in, no hosted database, no LLM required

Design principles

• Local-first: plain files and plain text. Git is the source of truth.

• Evidence-aware: every decision can carry links, commits, docs, tests, and conversations.

• Agent-compatible: structured enough for machines, human-readable enough for people.

• Boring by default: no magic, no black boxes, no forced workflow.

Roadmap

• CLI and Markdown ledger (shipped)

• MCP server with tools, resources, and governed prompts (shipped)

• local web dashboard (shipped)

• GitHub Action validation (shipped)

• cross-repository workspace aggregation (shipped)

• ADR import (shipped)

• policy/evidence change gates, attributed commits, sha256 seals, hash-bound reports, and SARIF output (shipped)

• token-budgeted decision context packs and PR context (shipped)

• cross-root workspace commit traceability (shipped)

• portable workspace packs and decision evidence packages (shipped)

• self-contained in-toto release audits and CI release-audit artifacts (shipped)

Why open source

Horizon Ledger is open source under MIT. The project will be developed and iterated by Codex as a local-first, agent-friendly decision ledger.

Contributing

Issues and pull requests are welcome. Please keep changes small and evidence-focused.

CI validation

Add this step to a workflow:

- uses: TTAWDTT/horizon-ledger/.github/actions/validate@main
  with:
    root: .
    strict: true

The Action installs Horizon from this repository and runs the same decision validator used by the CLI, so warnings and errors fail before the PR is merged.

To enforce opt-in policies, add the gate Action:

- uses: TTAWDTT/horizon-ledger/.github/actions/gate@main
  with:
    base-sha: ${{ github.event.pull_request.base.sha }}
    head-sha: ${{ github.event.pull_request.head.sha }}
    root: .
    artifact: true

To retain the decisions and gate verdict as one artifact, add the evidence Action:

- uses: TTAWDTT/horizon-ledger/.github/actions/evidence@main
  with:
    base-sha: ${{ github.event.pull_request.base.sha }}
    head-sha: ${{ github.event.pull_request.head.sha }}
    root: .
    artifact: true

To retain decisions, the gate verdict, and commit attribution as one release artifact, add the release-audit Action:

- uses: TTAWDTT/horizon-ledger/.github/actions/release-audit@main
  with:
    base-sha: ${{ github.event.pull_request.base.sha }}
    head-sha: ${{ github.event.pull_request.head.sha }}
    root: .
    artifact: true