GaosCode/PlanWeave

PlanWeave – A file‑backed loop‑engineering platform for coding agents

What it is – PlanWeave is a TypeScript/Node.js tool (CLI + Electron desktop app) that lets you turn a vague development goal into a structured, file‑backed task graph. Each node (a file) contains blocks (individual pieces of work). Blocks are claimed by specialized AI agents (Codex, Claude Code, OpenCode, Pi, Grok, or local scripts), run, reviewed, and the results are stored alongside the source files. The whole loop – planning, implementation, review, recovery – is recoverable and observable.

Why it matters – Chat‑based prompts are great for starting a plan but fragile for long‑running engineering. By making the plan a first‑class part of the repository (files = nodes, blocks = documents) PlanWeave keeps the state, history, and dependencies inside the project, enabling:

• Parallel work on independent blocks
• Automatic routing of each block to the most suitable agent
• Structured review feedback that feeds back into implementation
• Persistent run logs, artifacts, and metrics for later inspection
• Multi‑user collaboration and remote‑agent execution

Core concepts

Concept	Role
Package / Canvas	The top‑level PlanWeave project, stored as ordinary files in your repo.
Task graph	Nodes (files) linked by dependencies; each node holds one or more blocks.
Block	A claimable unit of work (e.g., “implement function X”).
Executor profile	A description of which AI model or local command should handle a block (e.g., codex-acp).
Agent skills	Small, reusable agents (plan-maker, plan-runner, plan-reviewer, …) that perform specific actions on blocks.
MCP server	A local HTTP tunnel that lets external LLMs (ChatGPT, Claude, etc.) call PlanWeave’s APIs to create or modify plans.

Key features

• File‑backed graph – the plan lives directly in your workspace, not in a separate database.
• Zero‑config start – install the CLI (npm i -g @planweave-ai/cli) and a few skill packages, then run planweave commands.
• Per‑block agent routing – pick the best LLM or a deterministic script for each block.
• Auto‑run mode – continuously claim ready blocks, invoke the executor, collect reports, and feed back review results.
• Desktop canvas – visual editor for tasks, blocks, dependencies, and run status (Electron app).
• Full audit trail – every run stores prompt, stdout, stderr, structured report, and metadata under the workspace.
• Collaboration – shared projects with member invites, task assignment, comments, and remote‑agent hosts.
• MCP integration – expose a local tunnel so ChatGPT (or other web‑LLMs) can drive PlanWeave via HTTP.
• Statistics & search – view efficiency metrics, search blocks, and see todo lists without leaving the tool.

Typical workflow

1. Create / import a plan – ask an LLM (via the plan-maker or plan-importer skill) to generate a package‑shaped draft from a high‑level goal or existing docs.
2. Validate & import – run planweave package-draft validate … and planweave package import … to materialize the plan in your repo.
3. Run the plan – invoke the plan-coordinator skill (or planweave run … directly). The coordinator claims blocks, dispatches plan-runner for implementation and plan-reviewer for review, and uses plan-recovery when needed.
4. Inspect & iterate – use CLI commands (planweave status, planweave graph inspect, planweave doctor) or the Desktop UI to see progress, view logs, and adjust the graph.
5. Collaborate – invite teammates, assign blocks, and optionally run agents on remote devices via the Agent Host feature.

Getting started

# Install the CLI (npm or Homebrew)
npm install -g @planweave-ai/cli
# or
brew install GaosCode/tap/planweave

# Install the bundled agent skills
npx skills@latest add GaosCode/PlanWeave

# Verify the install
planweave --help

• For a visual experience, download the Electron app from the repository’s Releases page.
• To enable ChatGPT‑driven planning, start the MCP server (planweave mcp tunnel …) and add the tunnel in ChatGPT’s tool settings.

Who should use it

• Developers who want AI‑assisted code generation but need reproducible, auditable runs.
• Teams building large codebases where multiple AI agents can work in parallel.
• Researchers experimenting with “loop engineering” – the cycle of prompt → execution → review → refinement.
• Anyone needing a durable, file‑backed representation of a multi‑step AI workflow.

License – MIT (see LICENSE).

---

All details above are taken directly from the repository’s README; no additional features have been inferred.