cafecito ☕

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

Status: v0.8 — a working single-repo control plane. 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, containers. 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 git+https://github.com/cafecitohq/cafecito   # or: pip install . from a clone
cafecito init --repo /path/to/your/repo --test-cmd "python3 -m pytest -q"
claude mcp add cafecito -- cafecito serve --repo /path/to/your/repo

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. watch shows it happening live:

(Real recording: one sentence → three agents → three gated landings → green main, 31s. Reproduce it: python3 examples/demo_swarm.py.)

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 four tools: sync (get the landed tip or a ready worktree), reserve (advisory leases on symbols before starting work), submit (land a committed changeset), status. 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. Symbol-level write sets for Python, TypeScript/JavaScript, and Go (stdlib scanners — 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 test suite — but verdicts are content-addressed by input closure, so only tests the landing actually touched execute; the rest inherit facts. 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.

Related MCP server: Geond Agent Protocol

The problem

Run five coding agents against one repo and you'll watch them gridlock: the first merge to main forces every other agent to rebase, rerun tests, and rejoin the queue. Merge queues serialize integration, so fleet throughput is capped at 1 / CI-duration no matter how many agents you run — and CI spend grows quadratically as everyone re-tests everyone else's rebases.

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

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