cafecito 0.18.1

An integration control plane for AI agent fleets: land in parallel, regenerate collisions, never resolve a conflict.

cafecito ☕

Your AI agents write code faster than they can merge it.

Point several coding agents at one repository and merging becomes the traffic jam: they line up, re-test against each other, and stall. cafecito clears it — independent work lands in parallel, real collisions are rewritten automatically from both sides' intent, and everything still passes your tests before it ships.

An integration control plane for AI agent fleets. Prove independence when you can. Re-derive when you can't. Never resolve a conflict.

Status: pre-1.0 — a working single-repo control plane (current version: see releases). The physics is validated (phase0/, bench/); the engine, MCP server, fleet (swarm/watch), PR gateway (ingest), memoized gates, and wave-parallel landing all run for real — and every feature since v0.1 landed through cafecito itself. Not yet: multi-repo, webhooks/hosted App. Sharp edges remain.

34 unedited seconds: three agents branch from the same commit; two commute and land in parallel, the third collides and is regenerated from both intents by a live reconciler call — gated, trailer-stamped, main green. Run it yourself: examples/demo.sh.

Quickstart

pipx install cafecito          # PyPI · or git+https://github.com/cafecitohq/cafecito for main
cd your-repo && cafecito init  # that's it

init reads your repo and reports what it did — no flags in the common case:

cafecito 0.16.0 on /Users/you/your-repo
  landed branch : cafecito/main
  tip           : 6712cbaeb828
  gate command  : npm test --silent
                  detected js — package.json scripts.test = 'vitest run'; 34 test file(s)
  setup command : npm ci
  mcp server    : .mcp.json written — commit it so every clone gets the plane
  advance hook  : post-commit — the tip follows commits made outside the plane
  agent docs    : AGENTS.md written; stanza appended to CLAUDE.md — commit it so agent sessions know to land

It detects your gate (pytest / npm test / go test / cargo test, including an app in a subdirectory), writes a checked-in .mcp.json so every session, clone, and worktree finds the plane, and installs a post-commit hook so commits made without the plane still move its tip. Override anything: --test-cmd, --redetect, --no-mcp, --no-hook, --no-agents. cafecito doctor re-checks all of it — including whether your gate can actually collect tests, because a gate that collects nothing lands everything unverified.

It also writes a short landing stanza into CLAUDE.md and AGENTS.md (appended, never overwriting what's there). This matters more than it looks: cafecito postdates every model's training cutoff, so no agent has heard of it. The MCP tools tell a session how to land; the stanza is what tells it that it should — and to stop and say so if the tools are missing, rather than quietly committing around the plane.

Add --ci and it scaffolds .github/workflows/cafecito.yml too: your test gate (generated from the plane's own config, so CI runs the command the plane lands on) plus a plane-sync guard that reddens when cafecito/main trails main — the CI-visible signal that a commit bypassed the plane. It's left alone on re-run, so your edits and version pins survive.

Commit .mcp.json and your teammates get the plane on their next session (each approves it once). claude mcp add cafecito -- cafecito serve --repo . still works for a single machine, but it binds to one directory: worktrees, other clones, and teammates won't see it, and sessions without the plane quietly commit around it.

Or skip the wiring and summon the fleet directly:

cafecito swarm "add rate limiting to the API, a retry helper, and tests for both" --agents 3
cafecito watch        # in another terminal: the live fleet dashboard

swarm plans the goal into independent tasks, pre-claims leases, runs the agents in parallel, and lands everything through the gate — commuting changes in parallel, collisions regenerated, contradictions escalated to you. Workers that drift outside their assigned paths get contained at the oracle's granularity: the symbols they actually wrote are leased before the changeset enters the pipeline (whole files only when a file can't be analyzed), so a fleet never knowingly races itself — and a sibling editing a different symbol in the same file doesn't wait, because symbol-disjoint writers commute. watch shows it happening live:

(Real split-screen recording, 35s unedited: cafecito swarm on the left — planner, three real agents, three gated landings, green main — while cafecito watch on the right streams the fleet, the leases, and the landed log live. Reproduce it: ./examples/demo_swarm_split.sh.)

Since v0.1, every feature of cafecito has been landed through cafecito — the story (including the release we broke and what it taught us) is in docs/building-itself.md.

Any MCP-capable agent then coordinates through five tools: sync (get the landed tip or a ready worktree), reserve (advisory leases on symbols before starting work), submit (land a committed changeset), status, and swarm. Commuting changesets land immediately; collisions are regenerated from both intents by a reconciler; every landing passes a real test gate; main is materialized as a normal git branch (cafecito/main). Agents never rebase and never see a conflict marker. Humans drive it from the shell: cafecito submit | status | log | advance — or keep opening ordinary GitHub PRs and let cafecito ingest land them through the plane.

What's underneath:

• Symbol-level write sets for Python, TypeScript/JavaScript, and Go — stdlib scanners, no parser dependencies. Anything unanalyzable widens safely to file granularity; other languages land at file granularity today.
• Verification facts. With gate_mode: full every landing gates on the whole suite, but verdicts are content-addressed by input closure, so only tests the landing actually touched execute — the rest inherit facts. Closures resolve Python, TS/JS, and Go inputs (import graphs, runner configs, lockfiles; Go rides whole packages). Anything the analysis can't see through statically — tsconfig paths, bundler aliases, workspaces, go:embed — simply runs the test instead of trusting a fact.
• Gate isolation. The gate executes candidate code, so isolation: sandbox (macOS) runs every test invocation with the network denied and writes confined to the gate's own worktree; a container backend (docker/podman, --network=none) ships experimental. Unavailable backends redden the gate — never a silent fallback to an unisolated run. Facts are keyed by isolation mode, so a green minted with the network open can't satisfy a sandboxed gate.
• Prepared worktrees. --setup-cmd (npm ci, pip install -e .) runs before tests in the gate's bare worktrees.
• Generated files (lockfiles etc.) skip merging and the reconciler: declare cafecito init --generated "package-lock.json=npm install --package-lock-only" and conflicts re-run the generator against the merged sources — in our TypeScript corpus that was 58 of 60 real conflicts.

Prove it locally: python3 -m cafecito.tests.smoke.

The problem

Point five coding agents at one repo and they stop behaving like five agents. The first one to land forces the rest to rebuild on top of it: pull the new code, re-run their tests, get back in line. Because a merge queue admits one change at a time, it doesn't matter how many agents you run — the fleet lands no faster than a single CI run (1 / CI-duration), and the CI bill grows quadratically as everyone re-tests against everyone else's landings.

The bottleneck isn't git's storage; it's three assumptions from the human era:

1. Line-based merge semantics — the system can't distinguish "independent" from "colliding," so it assumes collision.
2. Whole-repo serialization — every landing invalidates every other candidate.
3. Integration coupled to CI wall-clock — position changes in the queue trigger full re-tests whose results were already knowable.

The bet

Agent fleets invert the cost model of software integration: generation is nearly free; verification and coherence are scarce. Once regenerating code costs pennies, merging text is the wrong operation. cafecito is built on two primitives that follow:

• Commutativity-proven parallel landing. Changesets carry symbol-level write sets. Provably disjoint changes land in parallel — no rebase, no re-test (verification results are content-addressed facts, not rituals). Only true collisions serialize.
• Regenerative merge. When changes truly collide, no one "resolves the conflict": a fresh agent regenerates the overlapping region once, from both changes' intents and acceptance tests, gated by CI.

Coordination also moves earlier: agents take short leases on symbols at intent time, so contention is discovered before work is wasted, not at merge time.

Git stays as the interop boundary — main is always materialized as a normal git branch for humans, CI, and deploy tooling. Agents talk to the control plane through an MCP server and never run git rebase.

Vocabulary, used strictly throughout: changesets land; collisions commute, regenerate, or escalate; merge is reserved for git's textual mechanism and the market category it replaces (see SPEC.md §1.1).

Repository layout

Path	What	Status
phase0/	Falsification experiments A (commutativity rate) and B (regenerative-merge success rate) on real repos	active
SPEC.md	Protocol: changesets, leases, landed log, verification facts, MCP surface	v0 — all surfaces implemented
cafecito/	The product: oracle (py/ts/js/go/json write sets), engine (commute/regenerate/escalate, memoized gates, wave-parallel admission), MCP server, swarm/watch/ingest, CLI — pip installable, zero dependencies	active
sdk/	TypeScript / Python client SDKs	design
gateway/	Git gateway: materialized branch, advance, and PR ingestion (cafecito ingest, proven on PR #1); webhooks/hosted App pending	shipped in cafecito/
bench/	MergeBench — a real 33-agent burst: 5.5h serial queue vs 1.37h cafecito (10-min CI), 93.5 vs 16.2 CI-hours, landed for real with green main	active
PLAN.md	Full project plan, roadmap, and competitive analysis	living doc

Run the Phase 0 experiments

cd phase0
python3 run_corpus.py --repos <clones...>                           # A + conflict scan, many repos
python3 experiment_a.py --repo <path-to-clone> --since 2024-06-01   # commutativity rate
python3 find_conflicts.py --repo <path-to-clone>                    # attributed conflict corpus
python3 experiment_b.py --repo <path-to-clone> --max-pairs 5        # regenerative merge
python3 validate_b.py --repo <path-to-clone>                        # dual test-suite validation
python3 agent_corpus.py --repo <clone> --targets <files...>         # uncoordinated-fleet corpus

Python 3.10+ and git ≥ 2.38. Stdlib only — no dependencies. See phase0/README.md for methodology and current numbers.

License

Apache-2.0. Contributions require DCO sign-off — see CONTRIBUTING.md.

"cafecito" started as the codename and won the vote to stay. The coffee is load-bearing. Home: cafeci.to · code: github.com/Cafecitohq/cafecito