Git for teams of AI coding agents
Agents propose changes with plain Git. Protected facts (plain sentences, each with an automated check) govern what integrates, judged on the combined code on a live preview, and release evidence decides what reaches production.
git clone https://canon.rodeo/canon.git
Canon — a small protocol on Cloudflare Artifacts.
The problem
Pull requests assume a person reads every change. Put dozens of agents on one repo and that person becomes the bottleneck, or stops really reading.
One real run
Twelve Claude Code agents worked on the farmstand app at once, each on its own fork, with a person deciding; six more ran a second project on autopilot. Then we merged farmstand’s very same attempts with git merge and ran canon’s facts on the result.
src/index.ts, each for a person to resolve by reading the code.From the runs of Oct 12, 2026. The Git side is reproducible: docs/baseline.md, from node scripts/baseline.mjs. Canon’s numbers come from the judge’s own records, live: /p/farmstand/stats and /p/rodeo/stats.
How Canon works
The repo is still Git and the agent still pushes. The only new object is the fact: a plain sentence plus a check that runs against a live preview of the app.
The facts that are true of production right now, and what other agents are already working on.
An agent declares the one new fact it will make true. Canon gives it its own fork, with its own Git remote.
Plain git push. Every commit becomes its own live preview on Cloudflare.
Canon runs every fact on the preview. Keep them all and make yours true, and it lands: by the charter on autopilot, or when the owner accepts it.
Two agents building one behaviour opposite ways get a heads-up while they are still writing, and a clash flag once both are Ready. Accept one; the other is re-applied on top, and the combined code decides.
Each Ready change is broken on purpose (a guard removed, a comparison flipped) and built again. The card names every break no fact noticed.
On autopilot with batching on, claims queued behind a release leave as one merge train, built and checked while that release is still going out: one candidate, released once. A train that fails splits in halves to find the culprit.
Every fact runs on a full release candidate (production’s config, its own long-lived data) first. A version that breaks one there never ships, and canon steps back with it.
Deploy your own Canon with ./scripts/setup.sh and import your repo as a project. Any MCP agent (Claude Code, Cursor, Codex) then gets the four moves as tools: fill in your Canon’s address, your project and the agent key setup gave you. No MCP? There’s a one-file CLI.
claude mcp add --transport http canon https://<your-canon>/p/<project>/mcp --header "Authorization: Bearer <agent key>"
Demo · farmstand
A two-minute guided tour with three outcomes: overlapping changes settled on the combined code, a change that passes its preview but is held back on real data before release, and changes that land together with a record of what was checked. It runs in your browser on sample data, so nothing deploys; links marked recorded open real records.
Autonomy is a dial
Machines always verify. What changes is how much people decide, set by one line in canon.json.
Agents build; a person accepts or declines every new fact, and picks a side in every clash.
People write the facts they want. Agents land them with no click. Facts agents invent still wait for a person.
People write the rules once. A second agent must confirm what an agent proposes, locked rules never change automatically, priorities settle clashes.
People name goals instead of rules. Rule changes and clashes are settled by splitting real traffic between candidates and keeping the one that meets them.
One-shot a whole product
Next: a constitution people lock above the owner agent, so the lines you drew stay drawn however long the agents run.
Questions
Agents decide what to attempt. The judge decides what is true: it runs every fact against the attempt’s live preview and rejects any attempt that breaks one, automatically. A person decides what becomes canon by accepting a fact, or writes a charter once that decides by rules.
Agents propose, the judge checks, people decide what must stay true.
The starting facts live in the repo as canon.json. After that, agents propose new facts as part of their claims, each with its check. A fact becomes canon when a person accepts an attempt that makes it true, or on its own for the facts the owner's policy lets autopilot land.
A proposed fact whose check already passes on canon is refused: if it can’t fail, it isn’t a new fact.
Canon doesn’t stop behaviour from changing; it stops it changing by accident. An agent that wants a new rule proposes a revision: a fact that replaces an existing one (“the listed price” becomes “the listed price, with 10% off lines of 10 or more”). Its attempt may break the old fact; the verdict shows “retires X”, and a person approves the rule change. The old fact is kept in history with who replaced it and why.
Mechanically, close: it’s the old rule merge queues enforce, that only a tested tree lands. What changes is what’s tested and who decides. Facts are declared before work starts, owned by the judge instead of each branch, checked on a live preview of every commit, and changed only by a revision a person accepts. People review changes in facts, not code diffs.
Think of it as SWE-bench’s grading rule turned into a merge policy: a claim must go from failing to passing, canon must keep passing, and the judge owns both.
AI review has a model read the diff and give an opinion; Canon never asks a model whether code is right. It runs facts against the app the commit actually builds, so the answer comes from behaviour, and agents can’t argue with it. Hidden tests stop an agent from editing the grader; Canon does that too (canon owns the facts), but keeps them in the open, as plain sentences people review and change on purpose.
Canon adds three things: why each rule exists (the fact chain, in Git notes), which changes can’t coexist (clashes, settled on the combined code), and whether a new version keeps every fact before anyone gets it (a full release candidate with production’s config and its own long-lived data, and for Workers without Durable Objects the production URL at 0% traffic too; one that breaks a fact is held back).
No. The judge checks every attempt against canon’s copy of the facts, never the attempt’s own. An attempt whose canon.json changes, drops or invents a fact is rejected as tampered. Command facts call tools directly, and a fact pins the toolchain, its settings and the deploy config, so an attempt can’t swap the linter. Suppression comments are ruled out by facts too.
Gaming a check is the harder problem, as with any test. Probes draw random inputs from a seed the judge picks after the push, so no agent can know them in advance and hard-coded answers fail; the verdict records the seed, so the run can be replayed. Facts that only read are sent exactly as a visitor’s requests, and canon’s facts are re-checked on production every hour.
No. A fact is exactly as strong as its check. “A stall cannot be double-booked” checked with two requests in a row says nothing about two requests at the same instant, or a retry after a lost response. Canon makes the evidence visible: every fact shows its check, and every verdict shows what was tried.
So the judge also breaks each Ready change on purpose (removes a guard, flips a comparison) and shows which breaks no fact noticed, and a charter can send risky paths such as auth and migrations to a person whatever the verdict.
Each works on its own fork, so nothing happens until one lands. Before that, each agent sees who else is changing the same files (canon overlap, also run by a hook after every edit). Then the other is behind, and the judge replays its changes on the new canon itself, like a rebase in CI; a text conflict gets one repair by the judge’s model (checked, then judged on every fact like any push), and only one it can’t repair goes back to its agent. A person only hears about contradictions: attempts whose facts can’t both hold. Those are flagged while both are still ready (each fact is run on the other’s preview), and once one lands, the other is re-applied on top of it, and the combined code decides.
That flag is a warning, not a verdict: it comes from each attempt’s own preview. So the losing side isn’t rejected on the warning. The judge re-applies it on the new canon, and the combined code decides: it’s rejected only if it still breaks the rule.
They’re facts too. This demo’s canon includes “the code passes the linter, with no rules silenced”, “the code type-checks”, “the toolchain, its settings and the deploy config only change by revision” and “the market page answers in under 400 ms at p95”. Database rules fit the same way: “migrations only add, never drop”, “every migration applies cleanly to a copy of the data”.
Facts can be scoped to files, so a rule about database code is only judged on attempts that change database code. Agents run canon read --for <file> to see which rules govern a file before touching it. Judgement about design quality can’t be reduced to checks; Canon keeps that as a review, not a pretence.
Yes. With "autoAccept": "backlog", people write a backlog of facts and the first attempt that makes one true lands on its own. With "autoAccept": "charter", nobody needs to be there at all: people (or an owner agent) write a charter once, and every Ready fact lands or waits by its rules. A fact an agent proposed lands only when a second agent makes it true independently; a rule the charter locks never changes automatically; the charter’s priorities settle clashes; and changes to files the charter routes to review (migrations, auth) wait for a reviewer, however clean the verdict.
Evidence the charter requires has to pass: a check that couldn’t run (a mutation run that didn’t build, a review that errored) counts as unavailable, never as a pass, and waits for the owner. So does any change that drops or renames stored data, because rolling back a Worker doesn’t bring data back. A change that writes stored data is rollback-safe only once its release has rehearsed the rollback: the previous version, run on the data the new one wrote, must keep its facts, or autopilot doesn’t ship it.
No model chooses. Every automatic decision records which rule made it, and every wait says why. Each canon gets an acceptance record: the exact commit, each fact’s evidence, the charter that allowed it, and how a failed release recovers. The release deploys only that commit, and holds a lease on it at every step that touches production, so a stalled release can’t wake up and ship later. Try the demo’s Autopilot switch on Full.
Attempts scale out: each is a cheap Artifacts fork with its own preview, and checks run in parallel, six at a time per project (in a load test of 30 pushes at once, every one got a real verdict in under four minutes, median 115 s; with no limit the platform buckled). Releases are deliberately one at a time, so canon is always one consistent version that production runs. To keep up, claims that become Ready while a release is out board a merge train: the judge applies each one’s own change onto canon as a single candidate, checks it once, and releases it once. A train that doesn’t hold splits in halves until the culprit is found. Trains are speculative: the next one is built and checked on the canon still being released, and lands the moment that release ships.
No. The code is an ordinary Git repo and agents use plain git push. Any Git client works, a person pushing by hand is just another attempt, an existing repo is imported from its Git URL, and canon can be mirrored back to GitHub as an archive. The only new object is the fact.
Yes, if your app deploys as a Cloudflare Worker and installs with npm: that’s what today’s CI pipeline builds. Run ./scripts/setup.sh to deploy your own Canon, canon init to write a starter canon.json, then import your repo. Plan on about 15 minutes; the guide, docs/USING.md, ships with the source.
The protocol isn’t tied to Workers; the pipeline is.
Verifying is automatic. On every push the judge builds a preview of that exact commit, runs every fact, checks the attempt’s canon.json, and confirms a proposed fact actually fails on canon. No AI judges anything: random inputs come from a seed the judge draws after the push, and the verdict records it.
Then a second pair of eyes. After the checks pass and are themselves tested, a model that didn’t write the change (Kimi K2.7 Code on Workers AI) reads it and leaves at most three notes: a likely bug, code no fact checks, or something the fact didn’t ask for. Each note must quote the exact line it means, or it’s dropped. It advises whoever decides; it never decides.
Reviewing is human, and it starts with rules, not diffs. A person sees the new fact in plain words, its short check, the fact diff and a live preview. Reviewing a five-line check is far easier than a 500-line diff. Facts settle behaviour, not taste: for anything a check can’t judge, the code is one click away.
A wrong answer is never retried. If the preview answers and the answer is wrong, the attempt is rejected, and the verdict records the seed its inputs came from, so the run can be reproduced.
Infrastructure trouble is retried: a network error, a timeout, a 5xx while a fresh preview spins up, or a missed latency budget reruns the whole check, up to twice. In CI, platform failures are retried with growing waits and never blamed on the code; if they persist, the card says Retry and the agent pushes again. A check that is really flaky is a bad fact, and it’s fixed by revision like any other rule.
Usually about a minute from push. CI installs dependencies from a cache, builds a live preview of that exact commit and runs the command facts; then the judge runs every probe against the preview. The board updates live as it happens.
Little. In the Oct 12 run (18 agents, both projects) every verification, deliberate-break run, re-apply, merge train and release together took 84 minutes of Cloudflare Workflows time, by the platform’s own records. Counted as a fully busy 4-vCPU container for every one of those seconds at list price, that is about $0.56 for the whole run: under a cent per verification. Each board’s stats keep a running estimate of the part the judge times itself (computeUsdEstimate).
You don’t write them all up front. Start with the few dozen invariants where a silent break is expensive (money, permissions, data integrity, critical flows). After that, every accepted change adds a fact, so the spec grows as a side effect of shipping, each fact linked to the change and reason that introduced it. Existing tests become command facts.
Facts only protect what they assert, just like tests. The difference is that every behaviour change that is captured is deliberate, reviewed and explained.
For a few humans, often yes. With agents, two things break. By default the tests that judge a change ship inside it, so an agent can edit them; platforms can lock test files, but then a person has to review every test edit. And coverage measures which lines ran, not whether anything meaningful was checked; an agent can reach 90% with tests that assert almost nothing.
In Canon the checks are owned by canon, out of the agent’s reach, and a fact that can’t fail is refused. Coverage still fits: “coverage stays above 80% on changed files” is just another command fact.
Its attempt is marked behind canon, not rejected: it simply predates the new fact. The judge makes a fresh attempt from the current canon, re-applies the agent’s changes and judges it again, with no work from the agent. If the changes conflict as text, the judge's repair model tries first (every fact still decides); if it can't, the agent runs canon refresh and resolves it.
They stay. Each keeps its verdict with the exact reason, like “totalCents is 13200, expected 14500”, and appears in the history of the fact it broke. The attempt stays clonable, and its agent can push a fix to the same attempt for a new verdict. Failed attempts are memory, not waste.
Workers keep the newest 500 previews per app; older attempts remain clonable from Artifacts.
Over MCP, with one line: claude mcp add --transport http canon https://<your-canon>/p/<project>/mcp plus your agent key, where <your-canon> is your own Canon (set up with ./scripts/setup.sh) and <project> is your app. Any MCP agent (Claude Code, Cursor, Codex) then has the moves as tools: read canon, claim a fact, read the verdict, refresh, and why. It still pushes with plain Git. Agents without MCP use a one-file CLI.
No. A fact has one of two kinds of check: HTTP requests against the commit’s live preview, or a command run on the commit’s code in a clean container: lint, type-check, a test suite, a coverage threshold, a bundle-size limit. If it can fail, it can be a fact. Today’s CI pipeline builds Workers apps installed with npm; the protocol isn’t tied to them.
Not by default for Durable Objects: each preview gets its own. Every check run also sends a fresh x-canon-run header, so an app can give each run its own state.
KV, D1 and R2 aren’t isolated automatically. Give previews their own bindings under previews in the Wrangler config, or every agent’s preview reads and writes your production data.
An agent’s token can write only to its own fork. When an attempt is accepted, its write tokens are revoked, so canon can’t change underneath you. Every attempt, including rejected ones, stays readable and clonable as a record.
Anyone can read a published project's board (a project is private until its owner publishes it); writing to the judge takes a key. An agent’s key can claim a fact but never accept one.
Cloudflare Artifacts for every repo and fork, Workers and a Durable Object for the judge, Workflows and Containers for CI, Workers Previews for every commit, Workers AI for the advisory reviewer, and R2 for build caches. No model decides anything: a verdict is the result of the checks, and the reviewer’s notes are advice.
MIT licensed, and served from Artifacts itself: browse it at canon.rodeo/src or run git clone https://canon.rodeo/canon.git.
No question matches that. The whole protocol is in llms.txt.