The ledger and landing engine for code that agents write, on top of git and GitHub.
Code review, approvals, merge queues and release freezes all assume two things: writing a change is slow, and undoing one is expensive. A bad change cost days to write and days to unwind, so it was worth stopping everything to check it first. With agents writing the code, a change takes minutes, and so does a revert. Most of those gates now cost more than the mistakes they catch.
What lets them go is undo you can trust, and undo needs a record git doesn't
keep. git knows what changed. It doesn't know why, which agent session made
the change, what checked it, or whether that check ran somewhere the agent
couldn't touch. Without that, "undo everything that session did, across four
repos" is an afternoon of git revert by hand, and "is this green check real"
is a guess.
Conary keeps that record and builds on it:
- Every change has a why. Each pull request becomes a change with its intent (the task, a summary), its author and session, its class, every head it was pushed at, the evidence it landed on, and the landing itself. The record is an append-only, signed op log, anchored on GitHub so a log that loses entries is refused.
whyworks from anywhere. Ask why a line looks the way it does and get the change, its task, its session and its evidence. A fresh clone with no access to the ledger answers from git notes on the landed commits.- Evidence has to mean something. Agents don't grade their own work: a result counts only when it came from outside the authoring session and its producer vouches for it. A new test has to fail on the old code. Evidence names the exact tree it ran on, and never stands in for another.
- Changes land when their proof allows. The train checks every change that's ready with one gate run instead of one per PR, and lands the green ones in order.
- Anything can be undone. One change, every change one agent session landed, or everything since a point in time. An undo is always a new change through the same flow; nothing is rewritten.
- Only what undo can't fix waits for a person. Leaked secrets, dropped data and the owner's own decisions (class R2) still need someone to say yes. Everything else lands on evidence.
Conary isn't a new version control system. Agents keep cloning, committing and pushing with plain git, and trunk is the default branch on GitHub. An early draft planned a VCS of its own; that's parked until something turns up that can't be built on git, with the case written down. Nor does it run builds or tests: CI and other runners produce evidence, and Conary records it.
The full design, including what's parked and why, is docs/DESIGN.md.
Early. It runs on one machine, remi, over one owner's repositories, alongside burrow's steward, the service that gets PRs reviewed and merges them there today. Conary takes the steward's jobs over one at a time. So far it records every PR in those repositories, runs their merge trains, decides each change's class (which ones need a review round, and which a person) and opens undos. On remi it also works out its own landing decision for each PR after every steward pass and logs where the two disagree, acting on none of it; the steward still asks for the reviews and says when a PR is settled.
Where it's going, what's done and what's next are in the roadmap.
Conary records its own PRs, so this repository is the quickest look. With a full clone and cargo:
git clone https://github.com/FieldmouseWorks/Conary && cd Conary
cargo run --release -p conary-cli -- why --human crates/conary-core/src/why.rs:1
cn why fetches the notes from origin and names the PR that last touched
that line, what it was for, who made it and what it landed on. After that,
git log --notes=conary shows every landed commit's note
(notes).
cn keeps the ledger in $XDG_STATE_HOME/conary (or --ledger) and reads
GitHub with GH_TOKEN, or with each repository's own token from a command
(CONARY_TOKEN_COMMAND), as a GitHub App's are: one owner's each. The ledger
is anchored at a ref in the repository CONARY_ANCHOR_REPO names (the token
writes it): cn init sets it up once, and every write moves it on, so a log
that loses ops is refused. It prints JSON; add --human for people.
cn init
cn backfill FieldmouseWorks/burrow --reviewer <steward-app>[bot]
cn ingest FieldmouseWorks/burrow 61 --reviewer <steward-app>[bot]
cn log --human
cn why -C ~/src/burrow modules/claude.nix:40 --human
cn at 1762300800000 log --human # as the ledger stood then (ms since the epoch)
cn verify # the log against the anchor on GitHub, all of its history
Each write also brings the repository's notes up to date, and cn why in a
clone with no ledger beside it answers from them (notes).
cn class says what a PR's class is at a head, and whether it's
documentation only, so needs green CI and no review round
(class). The policy is a JSON file
(CONARY_POLICY) the machine gives it. The PR's labels can only raise
it: r2 makes it R2, and review asks for a review round, and a raise
stays once it's recorded. The class is recorded once per revision,
policy and labels, so asking again costs no more than reading the PR.
cn class FieldmouseWorks/remi 174 --head <sha> --human
cn policy FILE checks a policy file the way cn class reads it, refusing
a key it doesn't know, so a machine that checks its file when it builds it
can't pair a newer policy with an older cn.
cn train runs a repository's train (the
train) for the steward, as its App: join puts
a settled PR in at its head, classed by the same policy (an R2 one rides
alone), once --raised names every raise label (cn class's raised) it
has, the ones the steward settled it with, and step, on each of the repository's events,
builds the next candidate, reads its gate, and lands a green one's PRs in
order. --require names the checks the gate waits for even before they
report, and a step needs one: jobs of a shared CI, such as burrow's, whose
passes count only with the job's own attestation (CI
attestations), signed by the workflow the machine
names (CONARY_SIGNER_WORKFLOW) and made on one of GitHub's runners or on a
self-hosted one started fresh for that job, whose name starts with
--fresh-runners.
Services can also attest results with machine-configured public keys;
--producer-keys names the trusted keys and
the checks each can attest. This uses the same verifier as CI and flow.
verdict records one step can't tell: dropped, for a gate that never
finished.
export CONARY_SIGNER_WORKFLOW=FieldmouseWorks/burrow/.github/workflows/flake-check.yml
cn train join FieldmouseWorks/remi 174 --head <sha> --raised review
cn train step FieldmouseWorks/remi --require 'check / check' --fresh-runners fresh-remi-
cn train verdict FieldmouseWorks/remi <candidate> dropped
cn train show FieldmouseWorks/remi --human
cn undo opens the PR that reverts a landed change and records it as the
change's undo (undo); by session or time, one PR
per repo reverts each change, newest first. A revert that conflicts with
what came after it opens all the same, for its conflict to be resolved.
Every request needs --reason: a nonblank operational explanation, kept
on the undo operation and at the start of its PR body. For a red run, give
the run's URL, failing checks and first error line. Reasons enter permanent
history: never include secrets, personal data or prompt text.
cn undo FieldmouseWorks/remi#174 --reason 'Red run https://github.com/FieldmouseWorks/remi/actions/runs/123: check / check failed; error: build failed'
cn undo --actor https://claude.ai/code/session_01... --reason 'The session deployed the wrong configuration'
cn undo --since 1793750400000 --repo FieldmouseWorks/remi --reason 'Deployments since this time broke the health check'
cn attest is a CI job's side of the same evidence: it writes a gate's or
a negative run's attestation in the format, and
with --sign signs it with the job's own OIDC token (the job needs
id-token: write).
cn attest revision <base> <head> --result pass --tree <tree> \
--log flake.log --log-artifact flake-log-<uuid> --out "$RUNNER_TEMP/conary" --sign
cn attest job --audience AUDIENCE --repo OWNER/NAME is a door's side: whether a job's own
token, on stdin, may hand the machine something
(a job's own token).
cn plugin check PATH checks an executable against the versioned
plugin contract, with a copyable Rust example.
cn lessons check checks the lessons register as the
gate does, and cn lessons exit M6 is the lessons part of a milestone's exit
check: it fails while an open lesson applies to a component the milestone
ships (Properties).
cn --help and each command's --help list the rest, environment variables
included.
conaryd serves the same ledger over a Unix socket, as JSON-RPC, for
anything on the box (conaryd), and conary-mcp offers it
to agents as MCP tools (the MCP server). It can also tell a
gate whether CI already attested a pass on the same tree
(gate reuse).
The Rust workspace is in crates/. It needs only rustup and cargo, on any
Linux: rustup reads rust-toolchain.toml and installs the toolchain it pins.
cargo build
cargo test
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
With Nix, the flake runs the same checks in a sandbox. That's the gate CI runs:
nix develop # a shell with the toolchains
nix flake check # rustfmt, clippy and the tests, as above
MIT licensed. See LICENSE.
Explicit landing passes and dry-run decision comparisons are documented in cn flow. They do not switch repositories away from the steward.