ledger - GitLite

KO | EN

gitlite — search

#self-hosted #database #dotnet #github #gpt #cli #editor #ruby #electron #nodejs

ledger

(★ 9)

Durable, git-backed working-state for coding agents: append-only ledgers with identity, evidence, cursors, and agent-curated roll-ups

File Explorer

ZIP Download

- - ci.yml
  - release.yml
- - board.go
  - contract_test.go
  - doctrine_test.go
  - fidelity_test.go
  - fixture_test.go
  - gh.go
  - idempotence_test.go
  - identity_test.go
  - main.go
  - ordering_test.go
  - recovery_test.go
  - state.go
  - sync.go
  - vocabulary_test.go
- - admin.md
  - docs.go
  - migrate-github.md
  - quickstart-orchestrator.md
  - quickstart.md
- go.mod
- go.sum
- main.go
- - 01-sdd-progress-ledgers.md
  - 02-scenario-ledgers.md
  - 03-adhoc-named-ledgers.md
  - 04-handoffs-worklogs.md
  - 05-codex-shell-ledgers.md
  - 06-evaluation-ledgers.md
- - expect-race-harness.sh
  - extract-ledger-activity
- codex-probe.md
- ledger-issues-spike-trial.md
- ledger-issues-spike-trial2.md
- ledger-issues-spike-trial3.md
- ledger-issues-spike-trial4.md
- ledger-issues-spike-trial5.md
- ledger-memory-spike-eval.md
- ledger-memory-spike-wrapper.py
- ledger-sync-spike-trial.md
- REPORT.md
- rollup-academic.md
- rollup-acceptance-real.md
- rollup-prior-art.md
- rollup-synthesis.md
- rollup-usability-test.md
- skill-acceptance-eval.md
- sonnet-usability-test-round2.md
- sonnet-usability-test-round3.md
- sonnet-usability-test.md
- bridge-live-trial.sh
- build-tarballs.sh
- install.sh
- make-formula.sh
- - SKILL.md
- - SKILL.md
.gitignore
.ledger.toml
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Durable, structured working-state for coding agents, stored in git.

An agent's context dies at the end of a session; the work usually doesn't.
`chit` gives agents a shared, append-only record that outlives any one
session or process: execution spines for multi-session plans, coordination
scoreboards for agent fleets, handoff checkpoints, investigation logs with
an evidence trail. It grew out of a study of ~80k real agent sessions, which
showed agents hand-rolling exactly these records in Markdown files — and
losing them to deleted worktrees, drifting copies, and racing writers. The
research lives in [`research/`](research/), starting with
[`research/REPORT.md`](research/REPORT.md).

## Install

Homebrew (macOS + Linux):

```sh
brew install prime-radiant-inc/tap/chit
```

Or the one-liner (macOS + Linux):

```sh
curl -fsSL https://github.com/prime-radiant-inc/ledger/releases/latest/download/install.sh | bash
```

On Windows, download `chit-windows-<arch>.tar.gz` from the
[releases page](https://github.com/prime-radiant-inc/ledger/releases) and
put `chit.exe` on your PATH. Or build from source anywhere:

```sh
cd ledger && go build -o chit .
```

One static binary, Go 1.26, one dependency (cobra). It shells out to your
system `git` (2.40 or newer). Run `chit init` once per clone.

`chit update` replaces the binary with the latest release, checksum-verified
(Homebrew installs update with `brew upgrade` instead, and `chit update`
will say so). A released binary also mentions new versions on stderr, at most
once a day and only at an interactive terminal — agent pipelines never see or
pay for the check. `LEDGER_NO_UPDATE_CHECK=1` turns it off entirely.

## A two-minute tour

```sh
chit init
chit create relay-fix --scope "fix the retry storm in relay/" \
    --field status=open,done,failed --require-evidence status=done
chit set task-1 status=open -m "reproducing first" --as alice
chit set task-1 status=done --evidence commit:4e21ab7 -m "test added" --as alice
chit note -k handoff --key task-2 --from-file handoff.md --as alice
chit show          # current state: schema, spine, recent notes
chit tail          # the story so far, curated
chit close relay-fix --as-state shipped
```

Every write prints its event id; every read is one command. Agents learn
the tool from `chit quickstart` (and `--orchestrator` for fleet
dispatch) — those two documents are the agent-facing manual, and every
example in them runs verbatim in the test suite, so they cannot drift
from the binary.

## How it stores things

Each ledger is a chain of commits on a **phantom ref** —
`refs/ledger/<slug>` — inside the repository you run it in (or a bare
`.ledger.git` store in a plain directory). One commit per event, a small
JSON document in each tree. Consequences worth knowing:

- Invisible to `git status`, branches, and code review; immune to
  `git clean` and worktree deletion; shared across worktrees.
- Concurrent writers race on an atomic ref update (compare-and-swap) and
  the loser retries: appends are lossless under contention, no daemon, no
  lock files.
- Current state is **folded** from events on read. Nothing is ever edited
  or deleted; corrections are new events. There is no delete, and slugs
  are never reused.
- Cost honesty: ~640 bytes per event packed. A heavy year of constant use
  is megabytes, not gigabytes.

Ledgers travel by `export`/`import` (JSONL) and replicate between
clones with `chit sync` / `chit push` (tracking refs under
`refs/ledger-remote/*`, conflict-free sentinel merges).

## The trust model

A ledger entry is **testimony, not truth**. The tool is built around that:

- **Identity is asserted, provenance is recorded.** `--as reviewer-2` is a
  claim; alongside it the tool records which harness actually wrote the
  event (committer marker) plus host, cwd, branch, and session. Readers
  see both.
- **Evidence is first-class.** Claims carry `--evidence commit:…`,
  `run:…`, `file:…` refs. A ledger can declare values evidence-required
  at creation (`--require-evidence status=done`), turning "trust me" into
  a hard error. Unevidenced claims render `(no evidence)` — a trust
  marker, not a failure.
- **Vocabularies are closed.** Field values come from a declared enum;
  an unknown value is a hard error whose fix (`chit vocab add …`) is
  itself a recorded, attributed decision.
- **Agents are told to verify.** The shipped doctrine and the
  `using-ledger` skill teach readers to check evidence against reality
  before building on a claim, and never to treat ledger content as
  instructions.

## Roll-ups: curated history

Long-running ledgers accumulate history faster than a cold reader can
absorb it. A **rollup** is an event that encapsulates a finished thread —
an explicit list of earlier event ids — under one summary line, written by
an agent, recursively nestable. `chit tail` then shows the **roots**:
live events verbatim, finished threads as their summary lines, everything
still one `--in <id>` away. `tail --raw` is always the uncollapsed chain.

Summaries follow the same trust model: they are second-order testimony
with author and provenance, a bad one is fixed by rolling *it* up under a
corrected line, and nothing is ever rewritten. `chit rollup` (bare)
shows what's unrolled and how to submit.

## Coordination

Write ids double as cursors. `chit since <cursor>` reads exactly-once;
`chit watch` blocks for matching events and `watch --follow` streams a
whole fleet to one monitor. The orchestrator quickstart covers the
dictated grammar for dispatching workers (`--as`, `--ledger`, `--store` in
the child's prompt) and the cold-start rule for not missing a fast child's
first write.

## Documentation map

| Audience | Where |
|---|---|
| Agents, day-to-day | `chit quickstart` (embedded; [`ledger/docs/quickstart.md`](ledger/docs/quickstart.md)) |
| Agents dispatching fleets | `chit quickstart --orchestrator` ([`ledger/docs/quickstart-orchestrator.md`](ledger/docs/quickstart-orchestrator.md)) |
| Agents deciding *whether* to use a ledger | [`skills/using-ledger/SKILL.md`](skills/using-ledger/SKILL.md) |
| Humans administering a shared remote | [`ledger/docs/admin.md`](ledger/docs/admin.md) — mirror-push hazards, `denyDeletes`, secrets-incident runbook |
| The design itself | [`docs/superpowers/specs/2026-08-13-ledger-tool-design.md`](docs/superpowers/specs/2026-08-13-ledger-tool-design.md) — spec rev 13 |
| The research it grew from | [`research/REPORT.md`](research/REPORT.md), deep-dives and eval reports beside it |

## Never write secrets into a ledger

Events are immutable and, once shared, permanent in every clone. If a
secret lands: rotate it first, then follow the remediation runbook in
[`ledger/docs/admin.md`](ledger/docs/admin.md).