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.
- Zero-config start: install the CLI and agent skills, then use a few commands and skill prompts to create, run, and inspect a plan in an existing project.
- 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, Pi, or Grok for another, and use 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 ordered events, logs, reports, metadata, and available monitor actions.
- 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.
Use PlanWeave Desktop for visual planning and execution, or install the CLI for terminal workflows.
Install the CLI with npm:
npm install -g @planweave-ai/cliOr install it with Homebrew:
brew install GaosCode/tap/planweaveThen run:
planweave --helpInstall the agent skills as well:
npx skills@latest add GaosCode/PlanWeavePlanWeave Desktop provides a visual task canvas, task workspaces, Auto Run controls, run history, search and statistics views, and MCP tunnel settings for ChatGPT.
Install a packaged build from GitHub Releases. Current desktop installers are unsigned, so macOS or Windows may show a security warning. If macOS blocks the app, confirm it came from this repository and run:
xattr -dr com.apple.quarantine "/Applications/PlanWeave.app"For repository layout, source setup, tests, and packaging commands, see Development.
PlanWeave supports executor profiles, so different blocks can run through Codex, Claude Code, OpenCode, Pi, Grok, or local review commands. The runtime carries accepted results through review-feedback loops.
Each block run writes durable output under the PlanWeave workspace, including prompt, stdout, stderr, report, metadata, and monitor commands when available.
Custom package executor profiles must be trusted before use with planweave trust executor <profile>.
The repository includes focused agent skills under skills/:
plan-maker: design a PlanWeave package-shaped draft from a fuzzy goal or sparse codebase context, then materialize it through draft validation/import when requested.plan-importer: create a PlanWeave package draft from strong source docs, then validate, preview, and import it through the draft import flow.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. To materialize a plan, plan-maker writes a package-shaped draft and runs:
planweave package-draft validate --draft-root <draft> --json
planweave package-draft quality --draft-root <draft> --json
planweave package import --from <draft> --dry-run --json
planweave package import --from <draft> --apply --json- 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 graph inspect --view summary --json
planweave graph quality --json
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 a local HTTP MCP server for MCP clients such as ChatGPT. Its tools inspect and author plans by initializing projects, creating canvases, adding tasks and blocks, wiring dependencies, editing prompts, configuring review pipelines, validating graph quality, and importing package drafts.
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 write a package-shaped draft in a temporary draft root, dry-run validate and quality-check it, preview the import, then apply it transactionally.
Recommended headless setup for a VPS uses systemd. The MCP server stays on loopback, the OpenAI tunnel-client keeps an outbound connection open, and systemd manages the service lifecycle.
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 create, inspect, validate, and import PlanWeave plans through the MCP tools.
Source-level MCP server setup is documented in Development.
Auto Run claims ready work, invokes the selected executor, submits artifacts, continues review-feedback loops, and records each run as a session.
planweave run --once --json
planweave run --parallel --step-limit 20 --timeout 120000 --json
planweave run --scope task --task T-001 --once --json
planweave run --scope block --block T-001#B-001 --once --jsonThe executor is resolved from the block, task, and package defaults. Use --executor <profile> for an explicit run override and --canvas <canvas-id> to select a canvas.
PlanWeave Desktop provides scoped run controls, live progress, and session history. CLI users can inspect the same runtime state with:
planweave run-status --follow --json
planweave run-sessions --json
planweave run-session <session-id> --jsonPlanWeave provides explicit ACP profiles for Codex, Claude Code, OpenCode, Pi, and Grok: codex-acp, claude-code-acp, opencode-acp, pi-acp, and grok-acp.
Install and authenticate the selected agent, then verify and run its profile:
planweave executors test codex-acp --json
planweave run --once --executor codex-acp --timeout 120000 --jsonACP preflight negotiates the authentication methods advertised by the selected agent and can use credentials already configured for non-interactive authentication. If user action is required, CLI and Desktop show the next step; interactive login remains agent-owned and is not started automatically. PlanWeave does not persist agent credential values in run metadata or Desktop state.
ACP runs expose structured progress, artifacts, usage, and interaction requests through CLI and Desktop.
PlanWeave will continue to expand in three directions:
- Auto Run: improve execution control, recovery, and long-running reliability.
- Collaborative planning: let teams edit and refine the same task board together.
- Cross-host execution: coordinate specialized agents across different machines.
Contributor setup, repository layout, test commands, and local packaging notes live in DEVELOPMENT.md.
MIT. See LICENSE.