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