{
  "markdown": "<!-- mcp-name: io.github.ymxlx/polis-protocol -->\n<p align=\"center\">\n  <img src=\"assets/banner.png\" alt=\"Polis Protocol — three AI agents, one protocol, unified intelligence\" width=\"100%\" />\n</p>\n\n# Polis Protocol\n\n> 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.\n\n[![Website](https://img.shields.io/badge/website-polis--protocol.ymlsora.chatgpt.site-E8B24C)](https://polis-protocol.ymlsora.chatgpt.site)\n[![tests](https://github.com/ymxlx/polis-protocol/actions/workflows/tests.yml/badge.svg)](https://github.com/ymxlx/polis-protocol/actions/workflows/tests.yml)\n[![PyPI](https://img.shields.io/pypi/v/polis-protocol?label=pypi&color=2b7)](https://pypi.org/project/polis-protocol/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)\n[![Skill](https://img.shields.io/badge/format-Claude%20Skill-blueviolet)](SKILL.md)\n[![Vendor-agnostic](https://img.shields.io/badge/vendor-agnostic-success)]()\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n**🌐 Website → [polis-protocol.ymlsora.chatgpt.site](https://polis-protocol.ymlsora.chatgpt.site)** &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)\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"Polis benchmark demo — a synthetic repeat-error simulation followed by an advisory reservation conflict\" width=\"100%\" />\n</p>\n\n<p align=\"center\">\n  <strong>Synthetic simulation: repeat errors 65% → 7%</strong> &nbsp;·&nbsp; <strong>Advisory overlap conflicts detected</strong> &nbsp;·&nbsp; reproduce in 5s: <code>polis bench --mode learning</code><br/>\n  <sub>Modeled run with synthetic tasks and seed 0 — <a href=\"#proof-measured-honestly\">assumptions and limitations</a> are published below.</sub>\n</p>\n\n```bash\nuvx polis-protocol init      # one command · no server · no database · just markdown in your repo\n```\n\n<p align=\"center\">\n  Shared by <strong>Claude · Codex · Gemini · Cursor</strong>, all reading one <code>_polis/</code> folder. MIT.<br/>\n  ⭐ <strong>If the loop below clicks, a star helps other multi-agent builders find this.</strong>\n</p>\n\n---\n\n## The 10-second version\n\nThree AI agents share one project: **Claude** (research), **Codex** (frontend), **Gemini** (translation).\n\nA Spanish-translation task comes in. Who gets it?\n\nEarly 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.**\n\nThat 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:\n\n```bash\ngit clone https://github.com/ymxlx/polis-protocol.git\ncd polis-protocol && bash scripts/demo.sh\n```\n\n```\nScore breakdown (sorted by total):\n  gemini-translator-pesaj   total=0.688  hist=0.25  self=1.00  cost=1.00  avail=1.00  lessons=+0.10\n                              ↳ lessons applied: 2026-04-18-madrij-not-lider\n  claude-research-pesaj     total=0.453  hist=0.15  self=0.60  cost=1.00  avail=1.00  lessons=+0.00\n  codex-frontend-pesaj      total=0.290  hist=0.00  self=0.20  cost=1.00  avail=1.00  lessons=+0.00\n\nRecommendation: gemini-translator-pesaj   ← won on history + an applied lesson, not self-rating\n```\n\n> If that loop is interesting to you, a ⭐ genuinely helps other multi-agent builders find this.\n\n---\n\n## What it is\n\nThere 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.\n\nPolis adds an **active coordination layer** to the shared record:\n\n1. **Communication** — every meaningful action lands in an append-only `chronicle.md`. *(Every board does this.)*\n2. **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.)*\n3. **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.\n4. **Constitutional evolution** — when a rule stops working, citizens can propose, vote on, and ratify amendments to the protocol itself.\n\n> **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.\n\nThe 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.\n\nIf you are wondering how Polis compares with AGENTS.md, CrewAI, LangGraph, hcom,\nSwarmClaw, or agent memory systems, see [`docs/comparisons.md`](docs/comparisons.md).\n\n---\n\n## Why \"polis\"\n\nA *polis* is a small Greek city — a few thousand people who all know each other and run their own affairs. The metaphor maps cleanly:\n\n| Polis | Polis Protocol |\n|---|---|\n| Citizen | An AI agent from any vendor |\n| Capability card | A content-hashed YAML manifest of what an agent can do |\n| Contract | A structured task with intent, assignment, and settlement |\n| Chronicle | An append-only event log every citizen reads on session start |\n| Lesson | A retrospective filed by capability tag |\n| Chavruta | A paired critique by a citizen from a different vendor before a high-stakes action |\n| Amendment | A vote-ratified change to the constitution |\n\nIt 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.\n\n---\n\n## Quick start\n\n### Install\n\nFrom the root of any project:\n\n```bash\n# zero-install, one command\nuvx polis-protocol init\n\n# or install the CLI\npipx install polis-protocol      # isolated\npip install polis-protocol       # into the current env\n```\n\n`init` scaffolds `_polis/`, writes bridge files for Claude/Codex/Gemini, and\nregisters you as a citizen. Pass an identity when you want one:\n\n```bash\nuvx polis-protocol init \\\n  --agent-id claude-research-yourproject \\\n  --vendor anthropic --model claude-opus-4-7 --tool \"claude code\"\n```\n\nPreview the scaffold without writing files using `--dry-run`. Re-running is\nnon-destructive; `polis init --repair` restores any missing managed files.\n(Hacking on the protocol itself? `git clone` + `python scripts/init_polis.py`\nstill works.)\n\nYou now have:\n\n```\nyour-project/\n├── CLAUDE.md / AGENTS.md / GEMINI.md / AIDER.md ← cross-tool entry pointers\n├── .agents/skills/polis-protocol/SKILL.md ← skill mirror (Codex and Antigravity both read this)\n└── _polis/\n    ├── CONSTITUTION.md                    ← canonical protocol\n    ├── README.md\n    ├── index.md                           ← \"where things stand\"\n    ├── chronicle.md                       ← append-only event log\n    ├── citizens/<you>/                    ← capability_card, status, inbox, journal\n    └── contracts/\n        ├── open/                          ← active tasks\n        ├── settled/                       ← closed tasks with lessons\n        └── routing_stats.yml              ← learned routing policy\n```\n\n### Open a contract\n\n```bash\npolis contract open --title \"Literature review\" \\\n  --tags long-context-reading,source-checking --by claude-research-yourproject\n```\n\nOr drop a file in `_polis/contracts/open/` by hand — it's just markdown:\n\n```yaml\n---\ncontract_id: literature-review\nopened_by: claude-research-yourproject\nstatus: proposed\nstakes: medium\nrequired_tags: [long-context-reading, source-checking]\ncost_ceiling: medium\n---\n\n# Literature review of multi-agent coordination protocols\n...\n```\n\n### Route it\n\n```bash\npolis route --polis-root _polis \\\n  --contract _polis/contracts/open/literature-review.md --explain\n```\n\nOutput:\n\n```\nScore breakdown:\n  claude-research-yourproject  total=0.430  hist=0.00  self=0.90  cost=1.00  avail=1.00  lessons=+0.00\n  codex-frontend-yourproject   total=0.350  hist=0.00  self=0.50  cost=1.00  avail=1.00  lessons=+0.00\n\nRecommendation: claude-research-yourproject\n```\n\n### Settle and learn\n\n```bash\npolis contract settle literature-review --quality 5 --minutes 90\npolis reconcile --polis-root _polis\n```\n\nThe bandit's `routing_stats.yml` updates, and any lesson the owner files under\n`_polis/lessons/<tag>/` can carry a bounded `routing_effect` that the router\nreads — and names in `--explain` — on the next similar contract. Failures can\nbecome `polis guardrail add …` entries that future contracts on those tags\ninherit as must-pass acceptance criteria.\n\n### Don't collide\n\n```bash\npolis reserve src/auth --as claude-research-yourproject --note \"refactoring login\"\n# another cooperating Polis client receives a conflict warning with the holder named\npolis release src/auth --as claude-research-yourproject\n```\n\nReservations are advisory coordination recorded in shared state. They are not\nfilesystem locks, a security boundary, or a guarantee against races from tools\nthat do not participate in Polis.\n\n### Plug it into your agent over MCP\n\nEvery polis is also an MCP server — `polis mcp` speaks MCP over stdio with zero\nextra dependencies. It exposes the whole lifecycle as tools (status, open / route /\nclaim / settle / abandon, context packets, reserve / release, guardrails) plus\nread-only resources (`polis://state`, `polis://replay`, `polis://replay/redacted`,\n`polis://constitution`):\n\n```bash\n# Claude Code\nclaude mcp add polis -- uvx --from polis-protocol polis mcp\n\n# any other MCP client: command `uvx`, args `--from polis-protocol polis mcp`\n# (run it from inside the project, or add `--polis-root /path/to/_polis`)\n```\n\nAgents that can't shell out to a CLI can now open contracts, get an explainable\nrouting recommendation, reserve files, and settle with evidence — through the\nsame shared application layer the CLI and dashboard use. Nothing ever hand-edits\n`_polis/` files.\n\n---\n\n## Proof, measured honestly\n\n`polis bench` ships in the box — we benchmarked our own claims instead of asserting them:\n\n- **Repeat errors: −89%.** With lessons and guardrails auto-injected into matching future\n  tasks, the repeat-error rate falls from ~65% (a memoryless agent or unmanaged swarm) to ~7%\n  — each failure class recurs at most once, then becomes a standing check. Reproduce it:\n  `polis bench --mode learning`.\n- **Deterministic advisory conflict detection.** Within the benchmark, `polis reserve`\n  rejects overlapping claims and names the holder when every participant uses the same\n  shared state. Reservations are not filesystem locks or race prevention.\n- **And the part most projects won't tell you:** learned routing beats no-skill baselines\n  (random, round-robin) and recovers ~35–55% of an oracle's quality gain from outcomes alone —\n  but *accurate* static self-ratings stay competitive on quality, and the bench report says so\n  explicitly (`polis bench`). Polis's edge is learning *without having to trust the cards*,\n  a transparent reason for every pick, and the coordination layer the baselines lack.\n\n---\n\n## The four institutions\n\n### The Register\n\nEvery citizen publishes one file: `_polis/citizens/<agent-id>/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 what\". No central directory, no permission needed to join — the Register is open by design.\n\n### The Contract\n\nTasks are three-section markdown files:\n\n- **Intent** — goal, acceptance criteria, required tags, deadline, cost ceiling, stakes\n- **Assignment** — owner, plan, estimated effort (filled when claimed)\n- **Settlement** — outcome, quality self-score, what worked, what bit (filled when closed)\n\nOpen contracts live in `contracts/open/`. Settled contracts move to `contracts/settled/` and never get deleted. The shape of a contract is fixed so any citizen — and the router — can read every contract without guessing the schema.\n\n### The Chronicle\n\n`_polis/chronicle.md` is an append-only event log. One line per meaningful action:\n\n```\n- 2026-05-14 09:12 | claude-research-pesaj | drafted outline | [[contracts/open/literature-review]] | covers 2019-2025, 14 papers\n- 2026-05-14 09:15 | codex-frontend-pesaj  | settled contract | [[contracts/settled/auth-refactor]] | tests passing, lesson filed\n- 2026-05-14 09:18 | gemini-translator-es  | requested review | [[reviews/2026-05-14-0918-spanish-rollout]] | high-stakes, needs chavruta\n```\n\nReserved verbs (`opened contract`, `claimed contract`, `settled contract`, `filed lesson`, `requested review`, `proposed amendment`, `blocked on <thing>`, …) carry semantic weight that the router and other citizens parse on.\n\nLessons live separately in `_polis/lessons/<capability-tag>/`. The chronicle records what happened; the lessons record what was *learned*. Most events are not lessons, and most lessons distill many events.\n\n### The Amendment\n\nWhen a rule stops working, any citizen can propose a change. The proposal goes in `_polis/amendments/proposed/<id>.md`. Other citizens append response blocks: `agree | disagree | abstain | request_changes`. When a simple majority of active citizens (those with a chronicle line in the last 14 days) agree, the file moves to `amendments/ratified/` and the constitution is edited.\n\nThe protocol changes itself. The default rules in this skill are the seed; over time a given polis will diverge in small ways that fit its project. That divergence is the point.\n\n---\n\n## Chavruta review\n\nBorrowed from the paired-study model of the beit midrash, *chavruta review* is the polis's safeguard against single-model failure. Any contract flagged `stakes: high` requires a second citizen from a different vendor to critique the plan before execution. The critique answers three questions:\n\n> What is the owner getting right? What might they be missing? Decision: signed_off, requested_changes, or rejected.\n\nTwo citizens of the same vendor reviewing each other is allowed but weaker — the value of the chavruta is exactly the structural difference between models. Use it sparingly. Most contracts are low-stakes.\n\n---\n\n## How the router learns\n\nThe default router is a multi-armed bandit:\n\n- **Exploit** (85%): route to the citizen with the highest combined score on the required tags. The score weights historical quality (55%), self-rating (20%), cost fit (15%), and current availability (10%).\n- **Explore** (15%): route to a non-top citizen, weighted by score, to keep the policy honest about whether the current leader is still actually best.\n- **Cold start**: when no history exists for a tag, self-ratings dominate. Self-ratings get displaced within a handful of contracts per tag.\n\nWhen a contract settles, `routing_stats.yml` updates with the new quality score and minutes. That evidence can improve future recommendations as the record grows. The full math is in [`references/routing.md`](references/routing.md).\n\nYou can run the router as:\n\n- a 60-line Python script (`scripts/route_contract.py`),\n- a brief reasoning step inside any agent's session (the math is small enough to do in-context).\n\nBoth produce the same recommendation. Citizens can always override.\n\n---\n\n## Repository contents\n\n| Path | What it is |\n|---|---|\n| [`polis/`](polis/) | The installable package behind the `polis` CLI — routing, contracts, reservations, guardrails, context packets, bench, doctor, verify, migrate |\n| [`SKILL.md`](SKILL.md) | The Claude Code skill: when to activate, full workflow |\n| [`scripts/init_polis.py`](scripts/init_polis.py) | Bootstrap a new polis (idempotent, content-hashed cards, bridge pointers); thin shim over `polis/initializer.py` |\n| [`scripts/route_contract.py`](scripts/route_contract.py) | The bandit router and the `--reconcile` job; thin shim over `polis/routing.py` |\n| [`scripts/benchmark.py`](scripts/benchmark.py) | Polis Bench — routing vs baselines, and the repeat-error learning curve |\n| [`templates/POLIS_CONSTITUTION.md`](templates/POLIS_CONSTITUTION.md) | The canonical constitution written into every new polis |\n| [`templates/bridge_pointer.md`](templates/bridge_pointer.md) | The short `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` that points each tool at the constitution |\n| [`references/protocol-spec.md`](references/protocol-spec.md) | Full schema for every file (cards, contracts, lessons, amendments, reviews, status, inbox) |\n| [`references/templates.md`](references/templates.md) | Copy-paste templates for every file the protocol uses |\n| [`references/routing.md`](references/routing.md) | Bandit math, cold-start, explore-rate tuning, stats update procedure |\n| [`references/amendments.md`](references/amendments.md) | When to amend vs. when to file a lesson; quorum rules; worked examples |\n| [`references/troubleshooting.md`](references/troubleshooting.md) | Failure modes, recovery, scaling, and the migration path from `agent-vault` |\n\n---\n\n## Working across vendors\n\nThe protocol is vendor-agnostic. The same polis can be shared by Claude, Codex, Gemini CLI, Google Antigravity, Aider, GPT-based tools, and anything else that reads markdown. Bootstrap writes these discovery pointers:\n\n- `CLAUDE.md` — entry point for Claude Code\n- `AGENTS.md` — entry point for Codex, Jules, goose, opencode, Zed, Warp, VS Code, and Devin\n- `GEMINI.md` — entry point for Gemini CLI and Google Antigravity\n- `AIDER.md` — entry point for Aider\n- `.agents/skills/polis-protocol/SKILL.md` — skill mirror read by both Codex and Google Antigravity ([integration guide](docs/antigravity.md))\n\nThey all point at one place: `_polis/CONSTITUTION.md`. Updating the protocol means editing that one file.\n\nCross-vendor routing is where this protocol earns its keep. A Spanish translation goes to whichever citizen has the best track record on `spanish-translation`, not whichever happens to be the user's current chat. Over time, that means team output stops being bottlenecked by any single model's blind spots.\n\n---\n\n## Relationship to `agent-vault`\n\n[`agent-vault`](https://github.com/ymxlx/agent-vault) is a sister project: a simpler, communication-only protocol where agents share an Obsidian-style markdown blackboard. If you only need agents to leave each other notes, `agent-vault` is enough.\n\nPick **Polis Protocol** when:\n\n- You have agents from multiple vendors and routing matters.\n- You want recorded outcomes and lessons to inform future routing.\n- You want a way to amend the protocol itself when reality demands it.\n\nThe migration path from `agent-vault` is documented in [`references/troubleshooting.md`](references/troubleshooting.md).\n\n---\n\n## Status\n\n**v2.0 (stable) — [on PyPI](https://pypi.org/project/polis-protocol/) · [MCP registry](https://registry.modelcontextprotocol.io) · [website](https://polis-protocol.ymlsora.chatgpt.site).**\nThe protocol stays intentionally minimal — every file is markdown in your repo, the only dependency\nis PyYAML, and there is no required server or database. The `polis` CLI covers\n`init · route · reconcile · status · contract · reserve/release · guardrail · bench · serve · mcp · report · reflect · doctor · verify · migrate`,\nbacked by the full test suite in CI across Python 3.10–3.13. Schema v2 (`_polis/polis.yml`) migrates\nreversibly via `polis migrate --plan|--apply|--rollback`. Listing `polis mcp` in the official MCP\nregistry is a one-time manual step — see [`docs/publishing-mcp-registry.md`](docs/publishing-mcp-registry.md).\nForks, issues, and amendments welcome.\n\n---\n\n## Roadmap\n\nThe protocol layer is stable. Work in flight, in rough order of expected impact:\n\n- **`examples/` gallery** — 3 worked polises (research team, product team, OSS maintainer trio) to teach by example. Contributions welcome.\n- **Alternate routers** — a deterministic UCB1 variant ships behind `route_contract.py --policy ucb` and a seeded Thompson-sampling variant behind `--policy thompson` (both documented in `references/routing.md`), side-by-side with the default ε-greedy bandit. Benchmark harness on synthetic capability traces.\n- **Contextual bandit** — incorporate per-contract features (deadline pressure, stakes level, language) into the routing decision, not just per-tag history.\n- **Auto-rollover** — quarterly chronicle rollover and 90-day settled-contract archival as a one-line cron, so a year-long polis stays bounded without manual hygiene.\n- **Bridge expansions** — first-class entry pointers for Aider, opencode, Zed, Devin, Cursor agent mode. Each is a 30-line markdown stub.\n- **Polis-of-polises** — a documented pattern for multi-team projects where each subteam is its own polis and a thin meta-polis routes cross-team contracts.\n- **Visualizer** — small static dashboard that reads `routing_stats.yml` + the chronicle and shows the team's growth over time. (Bonus: dogfood it by opening it as the first contract in a fresh polis.)\n- **Academic write-up** — short paper situating Polis in the multi-agent-coordination literature (bandit-based task assignment, blackboard architectures, agent-based simulation).\n\nFile an [amendment-proposal issue](../../issues/new?template=amendment-proposal.md) if your need isn't on this list.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports, amendment proposals, new bridge tools, and worked examples are all valued. Security reports go to [SECURITY.md](SECURITY.md).\n\n---\n\n## Citing\n\nIf you use Polis Protocol in academic work, please cite it via [CITATION.cff](CITATION.cff) or the \"Cite this repository\" button on GitHub.\n\n---\n\n## License\n\n[MIT](LICENSE) — Yehuda Levy, 2026.\n",
  "bytes": 22228,
  "sha": "790db82b5d970f231ae1c5ff332b223b7bb5caec4ab3255429f22f9c87a3f156",
  "repo_slug": "yehudalevy-collab/polis-protocol",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yehudalevy_collab_polis_protoc_e1437d27/readme"
}