POLIS// PROTOCOL · V2.0Quick start

[ LOCAL-FIRST · MARKDOWN · GIT ]

Git-native coordination for coding agents.

Polis gives Claude Code, Codex, Gemini, Cursor, and other tools one shared _polis/ folder for tasks, owners, routing history, lessons, and decisions—without a hosted runtime or proprietary database.

View quick start View source
uvx polis-protocol init

One command. No server. No database. Plain files in your repo.

SHARED PROJECT STATE
AGENT / 01CLAUDERESEARCH
AGENT / 02CODEXIMPLEMENTATION
AGENT / 03GEMINIREVIEW
ONE SHARED WORKSPACE_polis/TRACKED IN GIT
03 ACTIVE CITIZENS01 OPEN CONTRACT12 LESSONS AVAILABLE

One folder every agent can understand.

The protocol owns only _polis/. Your project stays yours; the coordination record stays portable, reviewable, and diffable.

WORKSPACE / _POLISGIT STATUS: CLEAN
_polis/
├── CONSTITUTION.md
├── index.md
├── chronicle.md
├── citizens/
│   └── <agent-id>/
│       ├── capability_card.yml
│       ├── status.md
│       └── inbox.md
├── contracts/
│   ├── open/
│   └── settled/
├── lessons/
└── amendments/
01

Agent profiles

Capability cards describe each agent’s strengths, cost, and availability.

citizens/*/capability_card.yml
02

Structured tasks

Contracts keep intent, ownership, acceptance criteria, and settlement together.

contracts/open/*.md
03

Shared record

An append-only chronicle gives every vendor the same project history.

chronicle.md
04

Lessons + rules

Tagged lessons inform future routing; amendments evolve the protocol itself.

lessons/ · amendments/

Work moves through a visible loop.

Routing is explainable, ownership is explicit after a claim, and completed work leaves evidence the next agent can use.

  1. SEQ.01

    Initialize

    Create the shared _polis/ workspace and agent bridge files.

  2. SEQ.02

    Open

    Record a task with acceptance criteria, capability tags, and stakes.

  3. SEQ.03

    Recommend

    Compare capability cards and prior outcomes; explain the routing score.

  4. SEQ.04

    Claim

    Assign an owner and optionally publish advisory file reservations.

  5. SEQ.05

    Complete

    Settle the contract with outcome, quality, time, and evidence.

  6. SEQ.06

    Carry forward

    Load matching lessons and guardrails into the next relevant task.

[ OPERATING BOUNDARY ]

Coordination, not execution.

Polis makes shared intent and history explicit. It does not become a scheduler, sandbox, or security boundary.

What Polis coordinates

  • Structured tasks and claimed ownership
  • Explainable routing recommendations
  • Shared outcomes, lessons, and decisions
  • Advisory overlapping-path warnings

What Polis does not enforce

  • Agent execution or process scheduling
  • Filesystem locks or race prevention
  • Security isolation or permissions
  • Compliance by agents outside the workflow

A modeled learning effect—not field telemetry.

The bundled benchmark makes its assumptions inspectable and its result reproducible from the command line.

180 SYNTHETIC TASKS · 14 FAILURE MODES · SEED 0MODE: LEARNING
−89%MODELED REPEAT-ERROR RATE
In this simulation, a recorded failure becomes a standing check after its first occurrence. The result demonstrates the designed memory loop; it is not customer telemetry or a real-world error-rate guarantee.
View benchmark values as a table
Repeat-error simulation results
SetupTasksFailure modesRepeat-error rate
No persistent shared lessons1801465%
Polis learning model180147%

Use the protocol when routing and memory matter.

The strongest fit is a real repository shared by multiple coding agents—not every AI workflow.

Reach for Polis when

  • Two or more coding agents touch the same repository.
  • You switch vendors and prior decisions get lost.
  • Task ownership and routing quality need an audit trail.
  • Lessons should influence future matching tasks.

Skip it when

  • One well-prompted agent already handles the work.
  • You only need shared notes, not ownership or learned routing.
  • You need an execution runtime, scheduler, or security boundary.
  • Your agents will not maintain the shared records consistently.

[ 05 · QUICK START ]

Start with one command.

Python 3.10+ · MIT licensed · files stay in your repository

  1. 01

    Create the workspace

    Adds _polis/, bridge instructions, and your first agent profile without a hosted service.

    uvx polis-protocol init
  2. 02

    Inspect shared state

    Shows citizens, active contracts, reservations, lessons, and protocol health.

    polis status
  3. 03

    Open the first task

    Review the exact flags for title, capability tags, stakes, and the opening agent.

    polis contract open --help
Source Documentation Demo PyPI