Planr

Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.

idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> close

Why Planr

Flat todo lists break down the moment real work has structure. Planr models work as a dependency graph because that is what work actually is:

• Readiness is computed, not guessed. An item becomes ready only when its blockers are closed; planr pick returns work that is actually startable.
• Parallel agents need atomic claims. Picks are atomic claims enforced by the database — one item, one owner, no checklist races.
• "Done" is gated, not asserted. Closure requires log-backed evidence (files, commands, tests) and open reviews block their target.
• State survives sessions. Markdown plans hold scope and acceptance criteria; the SQLite graph holds live status across handoffs, restarts, and agent switches.
• Failure is structured. Stale picks, timeouts, and retries are detectable and recoverable (planr recover sweep).

Three layers make that work: Plans (reviewable Markdown packages), the Map (live dependency graph with picks, reviews, logs), and Agent loops (skills, CLI, and MCP workflows for every major coding agent). Full model: Task Graph Model and Operating Model.

Install

brew install instructa/tap/planr

Or via npm (ships platform-native binaries, no toolchain needed):

npm install -g planr

Or with the release installer:

curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh

Then initialize a project (also provisions the worker/reviewer subagent roles for your client):

planr project init "My Product" --client all

Manual downloads, from-source builds, and client wiring details: Install Guide.

Install The Plugin (Skills)

The plugin under plugins/planr carries the ten Planr workflow skills. Optional model-routing roles come from repository-local routing bundles. The planr CLI (above) is required separately.

codex plugin marketplace add instructa/planr
codex plugin add planr@planr

Inside a Claude Code session:

/plugin marketplace add instructa/planr
/plugin install planr@planr

Restart Claude Code afterwards. Skills are namespaced (/planr:planr, /planr:planr-loop), and the plugin registers the planr-worker and planr-reviewer subagents automatically.

One command installs everything the plugin would carry:

planr install cursor            # writes .cursor/mcp.json, .cursor/agents/, and .cursor/skills/
planr install cursor --no-mcp   # skills and subagents only, no MCP config

The dry-run also prints a one-click cursor:// deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: Cursor guide.

No plugin yet. Use Planr as an MCP server and paste the CLI prompt into your agent instructions:

planr mcp                   # stdio MCP server
planr prompt cli

Tell Your Agent

Two skills drive everything. $planr routes any request to the right stage skill from live map state; $planr-loop drives one feature through work, live verification, and independent review until the map is clean.

Start a new product from an idea:

Use $planr.

Create a production-ready Habit Tracker web app plan. Create the product plan,
split an MVP build plan, check it, then build the Planr map. Do not implement yet.

Ship one feature autonomously until verified:

Use $planr-loop.

Goal: ship the weekly overview feature. DONE when every in-scope map item is closed
with log evidence, all reviews are closed complete, and a live verification log shows
the feature working in the browser. Iteration budget: 10.

Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: Two Journeys. Watch progress anytime with planr map show.

What's new

• 1.5.0 — Optional routing policies: Planr Core stays provider-neutral while the independently buildable planr-routing package owns model policies and host bindings for Codex, Claude Code, Cursor, and mixed-host setups. Start with Routing Bundles, the planr-routing guide, and the 1.5.0 release notes.
• 1.4.0 — Verified presets: Added policy-driven composition, evaluation, signed registry evidence, and the public catalog. See the 1.4.0 release notes.
• 1.3.0 — Native host hooks: Added automatic session-state injection and loop recovery for supported hosts. See the Hooks guide and 1.3.0 release notes.

For the complete release history, see the Changelog.

Docs

• Install
• Skills
• Long-Running Goals
• Model Routing · Worked Example: Web App
• Host Hooks
• CLI Reference
• MCP Guide
• Codex · Claude Code · Cursor
• Operating Model
• Task Graph Model
• Architecture
• Testing
• Troubleshooting
• Specification Package
• More: Changelog, Import, Security, Handoffs And Stories, npm Package

License

MIT. See LICENSE.md.