agentplane

Define project policy once. Render it into every agent harness. Route work across providers. Get auditable results.

agentplane is a small, provider-neutral control plane for teams that use more than one AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, local models, or anything with a headless CLI). It does four things and nothing else:

It is not a skill library, an agent framework, or a swarm runtime. It sits under those and gives them one policy file, one routing table, and one result contract.

Install

Python 3.11+ and git. No other runtime dependencies.

pipx install agentplane          # or: uv tool install agentplane
# from a checkout or a release wheel:
pipx install .                   # or: uv tool install .

Provider CLIs are optional. Install whichever you use (claude, codex, cursor-agent, gemini, ollama); agentplane detects them and works offline with a built-in mock provider when none is present.

Use it with whatever plan you have

agentplane never talks to a model API itself. It launches the provider CLIs you already have, under the login and billing you already use, so pick the setup that matches your contract:

The model ids written by agentplane init are examples. Replace them with the ids your plan actually enables (each CLI can list its models), keep personal choices in ~/.config/agentplane/config.toml, and check the resolved command with agentplane run --role X --dry-run before spending quota.

Quickstart (5 minutes)

cd your-project
agentplane init                  # writes agentplane.toml + PROJECT.md, roles for the CLIs it finds
$EDITOR PROJECT.md               # describe the project once: purpose, stack, commands, quality gate, do-nots
agentplane render                # -> CLAUDE.md, AGENTS.md, .cursor/rules/project.mdc
agentplane routes                # what each role resolves to, and whether its provider is installed
agentplane doctor                # OK / WARN / NOTE; exit 1 only on real problems

Delegate a task and read the result:

agentplane run --role dry "Summarize the repo layout in five bullets"      # offline mock, always works
agentplane run --role review --read-only "Review src/ for missing error handling"
agentplane run --role impl --task-file PLAN.md --timeout 1200
cat HANDOFF.md                   # status, changed files, verification facts, provider output tail
agentplane runs                  # ledger of every run

Keep generated files honest in CI:

agentplane render --check        # exit 1 on drift
agentplane doctor                # exit 1 on WARN

Run the bundled offline eval suite:

agentplane eval run evals/suites/smoke --role dry

How it fits together

PROJECT.md ──render──▶ CLAUDE.md / AGENTS.md / .cursor/rules/project.mdc / GEMINI.md / …
     ▲                      (generated marker; `guard` and `render --check` protect them)
     │
agentplane.toml ── roles ──▶ run --role X ──▶ provider CLI (env allowlist, timeout, sandbox flags)
     │                                            │
     └── providers (built-in + packs + user)      ▼
                                       HANDOFF.md + runs.jsonl + log   ←── evals grade these

• Policy layer: PROJECT.md (+ optional per-target appendices in .agentplane/appendix/). Model aliases {{model:NAME}} expand from [models].
• Routing layer: [roles.*] in agentplane.toml; personal provider choices go in ~/.config/agentplane/config.toml and never into the repo.
• Execution layer: run launches the provider headless with an allowlisted environment, a timeout, and the provider's own sandbox flags; it never passes flags that disable a harness's approvals.
• Result contract: exit code 0 done · 1 failed · 2 usage · 3 safety boundary · 4 empty output · 124 timeout, plus the provider's typed self-report (DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT) read only from its last line.
• Extension: packs (pack.toml) add providers, targets, roles, and appendices. See packs/.

Full docs: docs/quickstart.md · docs/configuration.md · docs/routing.md · docs/handoff.md · docs/evals.md · docs/packs.md · docs/architecture.md · docs/security.md

Status

0.1.0, alpha. The Claude Code, Codex, and Cursor provider definitions mirror flags used in production; Gemini CLI is marked experimental. Provider CLIs change their flags; if one breaks, override the provider table in your user config and open an issue.

License

MIT — see LICENSE.