PlanWeave is a file-backed loop engineering system for long-running coding agents. It turns fuzzy plans into claimable tasks, routes them through implementation and review agents, records every run, and keeps the loop recoverable.
Chat is a useful place to start a plan, but it is a fragile place to run a long engineering loop.
PlanWeave turns a fuzzy goal or chat-authored plan into a task graph of nodes and block documents. Each block can be claimed by a focused agent, routed through implementation and review, and recorded as durable run artifacts. Agents get the current block plus relevant graph context, while the project keeps a recoverable history of what ran, what passed review, and what needs another loop.
That makes PlanWeave a better fit for complex engineering work: parallel implementation, staged checks, review feedback, follow-up fixes, continued execution, and progress tracking all stay inside the same local loop.
- Files are nodes, documents are blocks: the graph is not a decoration on top of chat. It is the project model.
- Graph-friendly by default: task flow, dependencies, review loops, and execution status are visible and editable.
- Scoped graph context: agents receive the current block plus relevant task graph context, and can inspect more when needed.
- Focused responsibilities: each claim hands one focused block to one agent, keeping context clean and avoiding unrelated plans, stale discussion, and wasted tokens.
- Per-node and per-block agent routing: use Codex for one block, Claude Code, OpenCode, or Pi for another, and local review scripts where deterministic checks are enough.
- MCP authoring for ChatGPT: connect ChatGPT to PlanWeave through the local MCP server, a headless systemd tunnel, or the desktop secure tunnel, then ask it to create canvases, tasks, blocks, review pipelines, and dependencies.
- Full auto-run workflow: PlanWeave can claim blocks, run agents, collect reports, handle review feedback, and continue the task flow.
- Review and feedback as first-class work: review blocks can produce structured feedback that returns to implementation blocks.
- Desktop and CLI support: use the visual Electron canvas or drive the same runtime from the terminal.
- Live observability: block runs keep logs, reports, metadata, and tmux attach commands for monitoring.
- Statistics, search, and todo views: inspect development efficiency and project state without leaving the workflow.
- Local-first and file-backed: plans, prompts, run records, and artifacts remain inspectable in your workspace.
For the default canvas, inspectable files live under canvases/default/package, canvases/default/state.json, and canvases/default/results inside the PlanWeave workspace. Use planweave paths --json for the exact local paths.
PlanWeave is currently CLI-first. The desktop app is available for testing, but it is experimental and unsigned.
Install the CLI with npm:
npm install -g @planweave-ai/cliOr install it with Homebrew:
brew install GaosCode/tap/planweaveThen run:
planweave --helpPlanWeave includes a local HTTP MCP server for using PlanWeave from MCP clients such as ChatGPT. The MCP tools are not just read-only status helpers: they can also author plans by initializing projects, creating canvases, adding tasks and blocks, wiring dependencies, editing prompts, configuring review pipelines, and validating the local project.
For ChatGPT in the browser, use the CLI MCP tunnel on a VPS or PlanWeave Desktop's MCP settings on a local machine. You can use ChatGPT Web as the planning partner: describe the project goal, ask it to draft the task graph, then let PlanWeave save the result as a canvas.
Recommended headless setup for a VPS uses systemd. The MCP server stays on loopback, and the OpenAI tunnel-client keeps an outbound connection open; PlanWeave does not run its own daemon or pidfile manager.
sudo mkdir -p /etc/planweave /srv/planweave
sudo chmod 700 /etc/planweave
planweave mcp tunnel download
planweave mcp tunnel configure --tunnel-id tunnel_xxx
planweave mcp tunnel print-systemd \
--planweave-home /srv/planweave \
--env-file /etc/planweave/mcp-tunnel.envPut the Runtime API key in the systemd environment file, not in PlanWeave's JSON config:
PLANWEAVE_HOME=/srv/planweave
OPENAI_RUNTIME_API_KEY=...Keep that file readable only by the service owner:
sudo chmod 600 /etc/planweave/mcp-tunnel.envInstall the printed service as planweave-mcp-tunnel.service, then run:
sudo systemctl daemon-reload
sudo systemctl enable --now planweave-mcp-tunnel
journalctl -u planweave-mcp-tunnel -fFor local desktop setup:
- Open Settings -> MCP Tunnel in the desktop app.
- Download or select the OpenAI
tunnel-client. - Enter your Tunnel ID and Runtime API key, then start the secure tunnel.
- Add PlanWeave in ChatGPT using the Tunnel connection mode.
Once connected, ChatGPT can ask PlanWeave for authoring rules and schema, generate a plan from your project goal, write it into a new task canvas, preview the execution graph, and validate the package before you run it.
Source-level MCP server setup is documented in Development.
PlanWeave supports executor profiles, so different blocks can run through different agents or local commands. Current executors include Codex, Claude Code, OpenCode, Pi, local review commands, and review-feedback loops.
Each block run writes durable output under the PlanWeave workspace, including prompt, stdout, stderr, report, metadata, and monitor commands when available.
The repository includes focused agent skills under skills/:
plan-maker: design a PlanWeave plan draft from a fuzzy goal or sparse codebase context before a formal package exists.plan-importer: create a PlanWeave Plan Package from project docs, with plan-quality checks before writing.plan-auditor: review an already-authored PlanWeave plan for coverage, lifecycle gaps, contract drift, weak prompts, and unverifiable completion criteria.plan-coordinator: keep a full PlanWeave execution loop moving as the main agent, dispatching implementation, review, and recovery work.plan-runner: execute one implementation block and produce a completion report.plan-reviewer: execute one review gate and produce a structuredpassedorneeds_changesresult.plan-recovery: diagnose and recover stale current refs, state/results drift, blocked/diverged work, and submit retry confusion.
Install them with the skills CLI:
npx skills@latest add GaosCode/PlanWeaveAfter installing the skills, use this flow in your target project:
- Ask your agent to create or import a plan.
Use skill: plan-maker
Create a PlanWeave plan for this project from the goal below...
If you already have PRDs, roadmaps, issues, or architecture notes, use plan-importer instead.
- Ask the coordinator to run the plan.
Use skill: plan-coordinator
Run the current PlanWeave package. Route implementation to plan-runner, review gates to plan-reviewer, and recovery work to plan-recovery.
- Let the coordinator dispatch focused agents.
The coordinator should assign one concrete block at a time. Implementation agents use plan-runner; review agents use plan-reviewer; abnormal state or submit retry problems use plan-recovery.
- Use the CLI for inspection when needed.
planweave status
planweave current
planweave explain <ref>
planweave doctorFor simple tasks, one agent can use plan-runner directly. For larger plans, use plan-coordinator as the main agent and route subagent work to plan-runner, plan-reviewer, or plan-recovery.
PlanWeave includes an experimental one-command execution path:
planweave run --once
planweave run --reset --force --reason "rerun acceptance" --step-limit 20
planweave reset --force --reason "clear stale manual work"
planweave run-sessions
planweave run-session SESSION-0001
planweave run-statusAuto Run can claim work, call an executor, collect run artifacts, continue review-feedback loops, and record each run/reset as a session. planweave reset clears runtime state only; it is separate from planweave init --reset-package, which rewrites package source files during initialization.
For cron-style runs, keep execution bounded and inspect the session log afterward. This example can be used directly in crontab:
0 9 * * * cd /path/to/project && planweave run --reset --canvas default --force --reason "scheduled run" --step-limit 10 --json >> ~/.planweave-cron.log 2>&1After a run, inspect the session log:
planweave run-sessions --jsonAuto Run is still experimental: scheduling, executor integration, and recovery behavior may be unstable. Inspect planweave run-status, planweave run-session <session-id>, and generated run artifacts before relying on it for unattended work.
Most users should drive PlanWeave through skills. The manual CLI loop is useful for debugging, demos, or writing your own agent integration:
planweave init --json
planweave validate --json
planweave current
planweave claim-next --dry-run
planweave prompt T-001#B-001
planweave submit-result --canvas default T-001#B-001 --report report.mdReview gates and feedback loops can be handled manually too:
planweave submit-review --canvas default T-001#R-001 --result review-result.json
planweave submit-feedback --canvas default --report feedback-report.mdPlanWeave resolves the target project root from the shell's current directory. Package managers may set INIT_CWD, which PlanWeave uses before cwd. When running from another directory, pass the global option before the subcommand:
planweave --project-root /path/to/project status --json
planweave --project-root /path/to/project claim-next --canvas desktopWhen scheduling is unclear, prefer planweave explain <ref>, planweave why-not <ref>, and planweave doctor before editing package or state files.
The desktop app is an experimental build. It is useful for trying the visual task canvas, configuring MCP tunnel access for ChatGPT, and reviewing generated plans before execution, but the CLI remains the recommended interface for serious work.
Install a packaged build from GitHub Releases. Current desktop installers are unsigned. macOS may show an unidentified developer warning, and Windows may show an unknown publisher or SmartScreen warning. For early testing on macOS, open the app with Right Click -> Open and confirm the prompt.
For repository layout, source setup, tests, and packaging commands, see Development.
PlanWeave is still early, and several directions can make plan-based agent work smoother:
- Better Auto Run UX and reliability: make automatic execution easier to understand, monitor, pause, resume, recover, and trust, while improving scheduling correctness, failure recovery, and long-running stability.
- Collaborative planning board: let multiple people edit the same task board, refine plan structure together, and turn shared planning decisions into executable blocks.
- Cross-host coordination: PlanWeave already supports routing different blocks to different local agents or executor profiles. A future coordinator could let remote Agent Hosts register capabilities, claim plan blocks through leases, report heartbeats, and submit artifacts safely, making it possible to run specialized frontend, review, runtime, docs, or other agents on different machines.
Contributor setup, repository layout, test commands, and local packaging notes live in DEVELOPMENT.md.
MIT. See LICENSE.