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.

New in 1.3.0: Native Host Hooks

planr install codex|claude|cursor now wires Planr into the host's native hook system by default — every new session (including post-compaction restarts) gets one compact state block injected automatically:

## planr state
project: Hookboard | map: 5/5 settled | 0 ready, 0 picked, 0 in_review
goal contract: DONE when every in-scope map item is closed with log evidence, ...
routing: registry active (3 profiles; pick packets carry model routing)
next: planr plan audit pln-fc584c28 --json

• planr prime — the state block behind the hooks: project, map counts, held items with log status, goal contract, and the next command. Silent in repos without a Planr database.
• Loop recovery becomes mechanism, not discipline — an agent that restarts or compacts mid-loop picks up exactly where the map says it left off.
• Evidence guard (Cursor) — a subagent that stops while its own pick has no completion log gets one advisory reminder naming the item and the two ways out.
• Fail-open and additive — hooks never block a session (10s timeout, always exit 0), existing hook files are merged, --no-hooks opts out.

Full guide: Hooks · Release notes.

Model Routing (1.2.0)

Declare once which model handles which work — every task then carries its own routing, and your agents delegate automatically:

# .planr/agents.toml  (write it with `planr agents init`)
[profiles.frontender]
client = "cursor"
model = "opus"
skill = "frontend-design"

[[routes]]
match = { work_type = "frontend" }
profile = "frontender"
fallbacks = ["driver"]

• Routing travels in the pick packet — planr pick --json hands the worker its profile, model, and paired skill; planr pick --peek lets dispatching drivers read it without taking the lease.
• Rendered into your hosts' native config — planr install codex|claude|cursor writes the subagent role files with model pins from the registry, in each host's exact vocabulary.
• Declared vs. actual, with receipts — workers report the profile they ran on, runs record the observed host, and planr trace item shows deviations as advisory markers.
• Use-case pools — free-form work types (frontend, backend, ...) declared right in the plan's task list (### TASK-001 (backend): ...), plus per-item pins via planr item route.

Routing is advisory by design: Planr never dispatches models and never blocks a pick — hosts stay the authority. Full guide: Model Routing · replayable walkthrough: Worked Example: Web App · Release notes.

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

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.

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
• 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.