planr

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 nine Planr skills plus the planr-worker and planr-reviewer subagent roles. The planr CLI (above) is required separately.

Codex

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

Claude Code

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.

Cursor

Pending marketplace review. Until the plugin is listed, wire Planr in via MCP and the CLI prompt:

planr install cursor        # writes .cursor/mcp.json
planr prompt cli --client cursor

opencode

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.

Docs

• Install
• Skills
• Long-Running Goals
• 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.