polis-protocol

<!-- mcp-name: io.github.yehudalevy-collab/polis-protocol -->
<p align="center">
  <img src="assets/banner.png" alt="Polis Protocol — three AI agents, one protocol, unified intelligence" width="100%" />
</p>

# Polis Protocol

> The local-first control plane for coding agents. Run Claude, Codex, Gemini, and Cursor against one repo — every task gets an owner, every handoff carries evidence, and the team measurably stops repeating its own mistakes. Plain markdown, in git, across every vendor.

[![Website](https://img.shields.io/badge/website-polis--protocol.vercel.app-E8B24C)](https://polis-protocol.vercel.app)
[![tests](https://github.com/yehudalevy-collab/polis-protocol/actions/workflows/tests.yml/badge.svg)](https://github.com/yehudalevy-collab/polis-protocol/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/polis-protocol?label=pypi&color=2b7)](https://pypi.org/project/polis-protocol/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Skill](https://img.shields.io/badge/format-Claude%20Skill-blueviolet)](SKILL.md)
[![Vendor-agnostic](https://img.shields.io/badge/vendor-agnostic-success)]()
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**🌐 Website → [polis-protocol.vercel.app](https://polis-protocol.vercel.app)** &nbsp;·&nbsp; [Install](#quick-start) &nbsp;·&nbsp; [Proof](#proof-measured-honestly) &nbsp;·&nbsp; [Plug into your agent (MCP)](#plug-it-into-your-agent-over-mcp)

<p align="center">
  <img src="assets/demo.gif" alt="30 second Polis Protocol terminal demo" width="100%" />
</p>

---

## 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:

```bash
git clone https://github.com/yehudalevy-collab/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 is the only one of these that is **active** — the coordination layer itself learns and governs:

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** — every settled contract produces a structured lesson; lessons feed back into the router so the team's wisdom compounds. **The team measurably gets better over time.**
4. **Constitutional evolution** — when a rule stops working, citizens propose, vote on, and ratify amendments to the protocol itself. *No other coordination tool ships this — it otherwise exists only in research papers.*

> **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`](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:

| Polis | Polis Protocol |
|---|---|
| Citizen | An AI agent from any vendor |
| Capability card | A content-hashed YAML manifest of what an agent can do |
| Contract | A structured task with intent, assignment, and settlement |
| Chronicle | An append-only event log every citizen reads on session start |
| Lesson | A retrospective filed by capability tag |
| Chavruta | A paired critique by a citizen from a different vendor before a high-stakes action |
| Amendment | A vote-ratified change to the constitution |

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:

```bash
# 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:

```bash
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

```bash
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:

```yaml
---
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

```bash
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

```bash
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

```bash
polis reserve src/auth --as claude-research-yourproject --note "refactoring login"
# another agent trying to grab src/auth/login.py is now rejected, with the holder named
polis release src/auth --as claude-research-yourproject
```

### 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`):

```bash
# 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: −88%.** With lessons and guardrails auto-injected into matching future
  tasks, the repeat-error rate falls from ~65% (a memoryless agent or unmanaged swarm) to ~8%