Polis Protocol

Polis Protocol

The local-first control plane for coding agents. Run Claude, Codex, Gemini, and Cursor against one repo — each claimed contract records an owner, agents can record evidence, and shared lessons help reduce repeated failures. Plain markdown, in git, across every vendor.

🌐 Website → [polis-protocol.ymlsora.chatgpt.site](https://polis-protocol.ymlsora.chatgpt.site) · Install · Proof · Plug into your agent (MCP)

Synthetic simulation: repeat errors 65% → 7% · Advisory overlap conflicts detected · reproduce in 5s: polis bench --mode learning

Modeled run with synthetic tasks and seed 0 — assumptions and limitations are published below.

uvx polis-protocol init      # one command · no server · no database · just markdown in your repo

Shared by Claude · Codex · Gemini · Cursor , all reading one _polis/ folder. MIT.

⭐ If the loop below clicks, a star helps other multi-agent builders find this.

---

The 10-second version

Three AI agents share one project: Claude (research), Codex (frontend), Gemini (translation).

A Spanish-translation task comes in. Who gets it?

Early on, Claude did — it rated itself highly. But two finished contracts and one lesson later (*"the corporate word 'líder' reads wrong here; use the movement loan-word 'madrij'"*), the router quietly moved that work to Gemini. Nobody reassigned it. The team learned, and the routing followed.

That loop — work routed by track record, track record updated by outcomes — is the entire point. See it yourself in one command, no install, no API keys:

git clone https://github.com/ymxlx/polis-protocol.git

cd polis-protocol && bash scripts/demo.sh

Score breakdown (sorted by total): gemini-translator-pesaj total=0.688 hist=0.25 self=1.00 cost=1.00 avail=1.00 lessons=+0.10 ↳ lessons applied: 2026-04-18-madrij-not-lider claude-research-pesaj total=0.453 hist=0.15 self=0.60 cost=1.00 avail=1.00 lessons=+0.00 codex-frontend-pesaj total=0.290 hist=0.00 self=0.20 cost=1.00 avail=1.00 lessons=+0.00

Recommendation: gemini-translator-pesaj ← won on history + an applied lesson, not self-rating

If that loop is interesting to you, a ⭐ genuinely helps other multi-agent builders find this.

---

What it is

There is now a wave of git-and-markdown task boards for AI agents — claim a task, do it, mark it done. They're good, and Polis can write to them. But a board is passive: it records what happened and never gets smarter. The protocol is frozen the day it ships.

Polis adds an active coordination layer to the shared record:

1. Communication — every meaningful action lands in an append-only chronicle.md. *(Every board does this.)*
2. Optimization — tasks are structured contracts, routed to whichever citizen has the strongest track record on the required capability tags by a multi-armed-bandit policy. *(A board can't; it has no notion of who's best.)*
3. Self-development — settled contracts can produce structured lessons; lessons feed back into the router and can help reduce repeated failures when the records are maintained consistently.
4. Constitutional evolution — when a rule stops working, citizens can propose, vote on, and ratify amendments to the protocol itself.

A board is something you fill in. Polis is a team that develops. It learns who's best, and it can rewrite its own rules.

The whole thing lives in a folder. There is no central server, no required runtime, no proprietary format. If a tool can read and write markdown, it can participate.

If you are wondering how Polis compares with AGENTS.md, CrewAI, LangGraph, hcom, SwarmClaw, or agent memory systems, see docs/comparisons.md.

---

Why "polis"

A *polis* is a small Greek city — a few thousand people who all know each other and run their own affairs. The metaphor maps cleanly:

It is opinionated on purpose. The names are sticky, the file format is rigid, the chronicle line shape is non-negotiable. Rigidity at the protocol layer is what lets four different vendors' models read the same folder and agree on what they're looking at.

---

Quick start

Install

From the root of any project:

# zero-install, one command

uvx polis-protocol init

or install the CLI

pipx install polis-protocol # isolated pip install polis-protocol # into the current env

init scaffolds _polis/, writes bridge files for Claude/Codex/Gemini, and registers you as a citizen. Pass an identity when you want one:

uvx polis-protocol init \

--agent-id claude-research-yourproject \ --vendor anthropic --model claude-opus-4-7 --tool "claude code"

Preview the scaffold without writing files using --dry-run. Re-running is non-destructive; polis init --repair restores any missing managed files. (Hacking on the protocol itself? git clone + python scripts/init_polis.py still works.)

You now have:

your-project/

├── CLAUDE.md / AGENTS.md / GEMINI.md / AIDER.md ← cross-tool entry pointers ├── .agents/skills/polis-protocol/SKILL.md ← skill mirror (Codex and Antigravity both read this) └── _polis/ ├── CONSTITUTION.md ← canonical protocol ├── README.md ├── index.md ← "where things stand" ├── chronicle.md ← append-only event log ├── citizens/ / ← capability_card, status, inbox, journal └── contracts/ ├── open/ ← active tasks ├── settled/ ← closed tasks with lessons └── routing_stats.yml ← learned routing policy

Open a contract

polis contract open --title "Literature review" \

--tags long-context-reading,source-checking --by claude-research-yourproject

Or drop a file in _polis/contracts/open/ by hand — it's just markdown:

---

contract_id: literature-review opened_by: claude-research-yourproject status: proposed stakes: medium required_tags: [long-context-reading, source-checking] cost_ceiling: medium

---

Literature review of multi-agent coordination protocols

...

Route it

polis route --polis-root _polis \

--contract _polis/contracts/open/literature-review.md --explain

Output:

Score breakdown:

claude-research-yourproject total=0.430 hist=0.00 self=0.90 cost=1.00 avail=1.00 lessons=+0.00 codex-frontend-yourproject total=0.350 hist=0.00 self=0.50 cost=1.00 avail=1.00 lessons=+0.00

Recommendation: claude-research-yourproject

Settle and learn

polis contract settle literature-review --quality 5 --minutes 90

polis reconcile --polis-root _polis

The bandit's routing_stats.yml updates, and any lesson the owner files under _polis/lessons/ / can carry a bounded routing_effect that the router reads — and names in --explain — on the next similar contract. Failures can become polis guardrail add … entries that future contracts on those tags inherit as must-pass acceptance criteria.

Don't collide

polis reserve src/auth --as claude-research-yourproject --note "refactoring login"

another cooperating Polis client receives a conflict warning with the holder named

polis release src/auth --as claude-research-yourproject

Reservations are advisory coordination recorded in shared state. They are not filesystem locks, a security boundary, or a guarantee against races from tools that do not participate in Polis.

Plug it into your agent over MCP

Every polis is also an MCP server — polis mcp speaks MCP over stdio with zero extra dependencies. It exposes the whole lifecycle as tools (status, open / route / claim / settle / abandon, context packets, reserve / release, guardrails) plus read-only resources (polis://state, polis://replay, polis://replay/redacted, polis://constitution):

# Claude Code

claude mcp add polis -- uvx --from polis-protocol polis mcp

any other MCP client: command uvx, args --from polis-protocol polis mcp

(run it from inside the project, or add --polis-root /path/to/_polis)

Agents that can't shell out to a CLI can now open contracts, get an explainable routing recommendation, reserve files, and settle with evidence — through the same shared application layer the CLI and dashboard use. Nothing ever hand-edits _polis/ files.

---

Proof, measured honestly

polis bench ships in the box — we benchmarked our own claims instead of asserting them:

• Repeat errors: −89%. With lessons and guardrails auto-injected into matching future tasks, the repeat-error rate falls from ~65% (a memoryless agent or unmanaged swarm) to ~7% — each failure class recurs at most once, then becomes a standing check. Reproduce it: polis bench --mode learning.
• Deterministic advisory conflict detection. Within the benchmark, polis reserve rejects overlapping claims and names the holder when every participant uses the same shared state. Reservations are not filesystem locks or race prevention.
• And the part most projects won't tell you: learned routing beats no-skill baselines (random, round-robin) and recovers ~35–55% of an oracle's quality gain from outcomes alone — but *accurate* static self-ratings stay competitive on quality, and the bench report says so explicitly (polis bench). Polis's edge is learning *without having to trust the cards*, a transparent reason for every pick, and the coordination layer the baselines lack.

---

The four institutions

The Register

Every citizen publishes one file: _polis/citizens/ /capability_card.yml. Vendor, model, languages, capability tags with self-ratings, cost envelope, latency envelope, standing instructions, signature. The card is the polis's answer to "who can do