polis

Polis

A multi-runtime plugin for coding agents. Polis fuses two disciplines into one workflow: context engineering (keep the agent's working memory lean and accurate) and spec-driven development with isolated subagents (think before building, build in small verified steps). It runs natively on Claude Code, Codex CLI, and Cursor.

Zero external dependencies. Markdown, JSON, vanilla JS, and Bash only. MIT licensed.

---

Why Polis exists

Coding agents fail in two predictable ways. They jump to code before anyone agreed what to build, and they fill their context window until accuracy quietly collapses. Polis is built to prevent both.

• A gated workflow — discuss → spec → plan → exec → verify — means code is the last step, not the first.
• Heavy work runs in fresh-context subagents, so the main session (the orchestrator) stays lean and sharp.
• TDD and atomic commits keep every step verifiable and reversible.
• Pause/resume state means a full context window is never a crisis — you save, compact, and pick up exactly where you left off.

The name is deliberate: a polis is a well-ordered city. The point isn't ceremony, it's that order in the small steps is what lets you move fast without making a mess.

---

The workflow

[describe what you want]
        │
        ▼
   ┌─────────┐
   │ DISCUSS │  Socratic Q&A, alternatives, gray areas → approved design
   └────┬────┘
        ▼
   ┌─────────┐
   │  SPEC   │  Executable spec: interfaces, edge cases, acceptance criteria
   └────┬────┘
        ▼
   ┌─────────┐
   │  PLAN   │  Atomic 2–5 min tasks, each with a test written first
   └────┬────┘
        ▼
   ┌─────────┐      ┌──────────────┐
   │  EXEC   │─────▶│  SUBAGENTS   │  fresh context per task, TDD,
   └────┬────┘      │  + 2-phase    │  atomic commits
        │           │   review      │
        ▼           └──────────────┘
   ┌─────────┐
   │ VERIFY  │  Full suite, lint, holistic spec compliance → merge-ready
   └─────────┘

Each phase needs your approval to advance. Polis proposes; you decide.

Meanwhile, the context monitor watches the window:

WARNING (40%+)  → start delegating, prefer short tasks
HIGH    (65%+)  → finish & commit current task only
CRITICAL(80%+)  → pause-work → compact → resume-work (skull)

How the monitor reads context: Claude Code exposes the live context state to the statusline, so Polis reads the real usage — no estimation. It judges thresholds on the figure that matches /context, and the bar leans a little early (a normalized value) as an action nudge. CRITICAL means CRITICAL.

---

Get Polis

If you use Claude Code, you can skip downloading entirely — the marketplace path below fetches everything for you. For Codex, Cursor, or if you just want the files, get them one of these ways:

Clone with git (recommended if you have git):

git clone https://github.com/ilry-polis/polis.git
cd polis

Download the ZIP (no git needed): on the GitHub repo page, click the green Code button → Download ZIP, then unzip it and open the folder:

unzip polis-main.zip
cd polis-main

Either way you end up in the Polis folder, ready to run the installer.

---

Install

Path A — Claude Code marketplace (Claude Code only)

/plugin marketplace add ilry-polis/polis
/plugin install polis@polis-marketplace

One line, no manual download. This is the simplest path if you use Claude Code.

Path B — the installer (any runtime)

From inside the Polis folder (see Get Polis above), run the installer for your runtime:

bash scripts/install.sh --runtime claude --scope project   # claude | codex | cursor | all

Flags:

• --runtime claude | codex | cursor | all
• --scope project (this repo) | user (your global runtime config)
• --uninstall — removes Polis cleanly (marker-bounded; never touches your work)
• --dry-run — show what would happen, write nothing

Codex and Cursor don't have a one-line marketplace path equivalent to Path A — use Path B for those.

Then initialize

Once installed, set Polis up in your project:

/polis:init

---

Commands