planr

Planr

Planr is a local-first task planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, and other MCP-capable clients can coordinate safely.

Table of Contents

• Why a Graph-Based Planner
• Product Direction
• Quick Start
• From Source
• Target Agents
• Current Repository Contents
• Install The Plugin (Skills)
  • Codex
  • Claude Code
  • Cursor
  • opencode
• Integrations
• Verification
• Specification Package
• Guides
• License

Why a Graph-Based Planner

Flat todo lists and Markdown checklists 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. A flat list cannot express "B cannot start before A is closed." In the graph, an item becomes ready only when its blockers are closed, so an agent never has to interpret a checklist — it asks planr pick next and gets work that is actually startable.
• Parallel agents need atomic claims. Two agents editing the same checklist is a race condition. Picks are atomic claims on ready items: one item, one owner, enforced by the database, not by convention.
• The critical path is a query. "What unblocks the most downstream work?" and "what is the longest remaining chain?" are unanswerable with a list. With a graph they are one command: planr map lane --critical and planr map pressure.
• "Done" is gated, not asserted. Closure requires log-backed evidence (files changed, commands run, tests) and open review items block their target. A checked checkbox proves nothing; a closed graph node carries its proof.
• Nesting gives context without losing state. Markdown plans hold scope, acceptance criteria, and narrative; the graph holds live status. Chat history evaporates between sessions — the graph survives handoffs, restarts, and agent switches.
• Failure is structured. Stale picks, timeouts, and retries are detectable and recoverable (planr recover sweep) because state lives in a database instead of someone's memory.

The result: multiple coding agents can work the same repository concurrently without stepping on each other, and a human can audit at any time what is done, what is blocked, and why. See docs/TASK_GRAPH_MODEL.md and docs/OPERATING_MODEL.md for the full model.

Product Direction

Planr combines three layers:

• Plans: reviewable Markdown artifacts for product specs, PRDs, architecture, UX, build contracts, and reviews.
• Map: the live dependency graph for items, links, picks, reviews, logs, and progress.
• Agent loops: provider-neutral CLI and MCP workflows for Codex, Claude Code, Cursor, and generic clients.

The product flow is:

idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close

Planr ships as a self-owned Rust CLI with SQLite graph storage, Markdown plan packages, recovery sweeps, scoped Git review evidence, reusable packages, MCP stdio integration, prompt output, and a localhost HTTP/SSE surface with a browser review workspace.

Quick Start

Install the current GitHub Release:

curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh

Manual release downloads are published at:

• https://github.com/instructa/planr/releases

Release assets for darwin/linux on arm64/x86_64 are built and published automatically by the tag-driven pipeline described in docs/RELEASE.md.

Homebrew is the preferred package-manager path once the tap is published:

brew install instructa/tap/planr

After install:

planr project init "Example Product" --client all
planr plan new "Inventory API" --platform api --backend
planr plan split <plan-id> --slice "MVP backend"
planr map build --from <build-plan-id>
planr pick
planr log add --item <item-id> --summary "Implemented first slice" --files src/api.rs --cmd "cargo test"
planr review request <item-id>
planr review evidence <item-id>
planr review close <review-id> --verdict complete
planr close <item-id> --summary "Verified"

Use --json for automation and --db <path> for isolated databases.

From Source

Maintainers and contributors can run the CLI directly from the Rust workspace: