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.

View the Demo →

Documentation →

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. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin:

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

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

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   # project skills, subagents, and hooks; 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.

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

Remember one public entry point: $planr. It routes the request from live Planr state, including planning-only work and autonomous-goal preparation. Stage skills are advanced surfaces selected by the router.

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.

For a long autonomous run, prepare outside the driver first. The preparation result prints a real plan id; Codex or Claude Code then starts only the plan-bound loop driver:

Use $planr to prepare an autonomous goal for the weekly overview feature.

/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr
context (tag: goal-contract).

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.