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 declarations live in repository-local files such as .planr/agents.toml and .planr/policy.toml; external tools may manage those files, but Planr does not install or invoke a routing engine. 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 ordinary planning and status work from live Planr state. For long autonomous runs, use the explicit two-step workflow: $planr-goal prepares durable state, then $planr-loop executes the resulting plan.

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-goal 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. Coding agents inspect progress with the compact default planr map show or, preferably, planr map show --json. The tree preserves exact dependency vocabulary while marking satisfied edges as blocks✓; active blocks stay red. The boxed planr map show --view diagram renderer is exclusively for human supervision and uses neutral then routes once those dependencies are satisfied. Agents must not invoke it. Humans can add --full for complete status, title, worker, critical-lane, and pressure details. Interactive map output colors states automatically; --no-color and NO_COLOR keep it plain.

To supervise an agent from a second terminal, leave the agent running in terminal A and watch its scoped graph in terminal B:

planr map watch --plan <plan-id>
# optional: exit after every scoped item settles
planr map watch --plan <plan-id> --until-settled
# optional: inspect complete node details
planr map watch --plan <plan-id> --full

The watcher is likewise a human-only observer. It defaults to the condensed diagram view, polls the local SQLite graph once per second, and redraws only when state changes. Coding agents must not invoke map watch; they should use map show --json snapshots or the /v1/events/stream SSE endpoint instead. Use Ctrl-C to stop.

What's new

• 1.7.0 — Evidence-backed evaluations: Added durable eval suites, runs, comparisons, invalidation and rescoring, correctness/quality/performance gates, cost per verified success, and effort recommendations. The complete workflow is available through the CLI; MCP only mirrors selected surfaces and is optional. Security gates now cover repository leaks, vulnerable dependencies, workflow hardening, privacy, and forbidden staged files. See the Eval Contract, CLI Reference, and the 1.7.0 changelog.
• 1.6.0 — Human map observation: Added a condensed boxed diagram, live two-terminal watching, accessible state colors, and clearer satisfied dependency routes. These views are intentionally for human supervision; agents keep using the default tree or JSON snapshots. See Task Graph Model, CLI Reference, and the 1.6.0 changelog.
• 1.5.2 — Standalone core, optional Switchloom: Planr consumes provider-neutral repository declarations and route evidence only; it works without any routing files, and requested-only routing metadata is not execution proof. Optional model-routing lifecycle is external, with Switchloom v0.2.1 verified as the repository-local handoff outside Planr. Start with Model Routing, Switchloom, the Switchloom repository, its tagged setup quickstart and lifecycle docs, and the Changelog.
• 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.