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  ·  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/<you>/                    ← 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/<tag>/ 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