Planwright standalone

Planwright is a local planner shared by a human and an AI coding agent. The agent authors plans and records evidence through MCP; the human reviews intent, ratifies plans, and accepts or requests changes through the web UI.

This repository contains the standalone React planner, SQLite core, MCP/CLI, and reusable workflow engine. Code intelligence comes from external Vex. The older Next.js application, hosted agent fleet, memory service, token-usage collector, and built-in code index are retired.

Run from source

Use Node.js 22.22 or newer, Corepack, and the repository-pinned pnpm version (pnpm@11.24.0). SQLite uses better-sqlite3; native compilation may require your platform's compiler toolchain if a prebuilt binary is unavailable.

git clone https://github.com/soundheart-studios/planwright.git
cd planwright
corepack pnpm install --frozen-lockfile
make build

Initialize a project from its own folder. Replace the CLI path below with your absolute checkout path:

cd /path/to/your-project
node /absolute/path/planwright/packages/mcp-server/dist/cli.js init
node /absolute/path/planwright/packages/mcp-server/dist/cli.js web

Open http://127.0.0.1:4400. Initialization creates the project's .planwright/ data, registers it in the local project list, and installs MCP configuration and workflow instructions for Claude Code and Codex. Reload the agent connection after initialization. Existing installations with a pw command can use pw init and pw web directly.

The existing macOS installation also answers at http://planwright through its local front door. A fresh source checkout uses the loopback URL above; this repository does not install the old hostname relay. The server binds to loopback and uses a local human actor; it is not a public multi-user service.

From the checkout, make web builds and starts the planner. make web-status, make web-stop, and make web-restart operate on the owned local service. The UI is a production build, so restart it after source changes.

Related MCP server: AgentSync MCP Server

The planning loop

1. The agent interviews you and seeds a structured plan with phase outcomes, task descriptions, acceptance criteria, test references, and dependencies.

2. You review and ratify the plan. Ratification is human-only; a draft cannot execute merely because an agent bound to it.

3. The agent records intent, demonstrates a failing test, implements the work, records a passing run, and commits task work. Removal verification proves that the tests detect the subject they claim to cover.

4. Each criterion maps to its evidence through criterionRefs. Completion requires the existing evidence, coverage, drift, and verification gates.

5. Material revisions arrive for human review. Reviews pin their content; changed content requires an explicit refresh before acceptance.

The MCP connection identifies the project. Call plan_list, then plan_bind with an exact plan ID/name or an unambiguous task ID. Binding selects the plan for that session; it does not ratify it or grant an exception to any gate.

The UI provides project and plan selection, phase navigation, an all-phases view, completed-task history, a task inspector, ADRs with task links, and inline plan/revision review. Reading positions have URLs and survive refresh and Back/Forward navigation.

Completed tasks show a seven-character commit reference; clicking it copies the full SHA. New completions use the explicitly accepted run. Completed legacy tasks without completion metadata can show an existing passing run's SHA labeled Historical commit reference. That display fallback creates no completion receipt and changes no stored evidence. Copying supports the local HTTP address as well as the secure-context Clipboard API.

Reusable workflows

The workflow engine stores immutable definitions and exact revisions. The UI shows the shared catalog and each plan's pins, local variants, origins, and recent runs. Agents author workflow definitions through MCP.

workflow_catalog_list {}
workflow_catalog_describe {name: "review", revision: 1}
workflow_bind {name: "review", revision: 1}
workflow_bindings {}
workflow_run {bindingId: "<returned pin id>", input: <declared input>, purpose: "adhoc"}

Use a workflow actually present in your catalog and its declared input shape. Import copies pinned definitions and dependencies into the project. Existing pins never silently upgrade. Ad hoc runs do not count as task evidence. Stochastic steps still require their configured provider; catalog persistence does not prove a provider integration works.

PLANWRIGHT_WORKFLOW_REGISTRY selects the shared workflow directory. PLANWRIGHT_REGISTRY selects the project-list JSON file; these are separate registries. PLANWRIGHT_LOCAL_STATE selects local web-service state.

Data and existing projects

Each project owns its .planwright/planwright.db. Local project registration and service state normally live under ~/.planwright/. The standalone planner retains historical database rows and receipt compatibility. Normal access migrates the selected database additively; the cutover did not blanket-upgrade all registered projects.

After updating the source, rebuild and refresh a selected project explicitly:

make install build
cd /path/to/your-project
node /absolute/path/planwright/packages/mcp-server/dist/cli.js upgrade

upgrade --all refreshes every registered project; use it only when that is your intended scope. Back up databases consistently before operational changes. Keep operational backups and rollback records outside the public source tree.

The core also retains case packs and claim/document evidence checkers. Their historical records remain compatible; the standalone UI concentrates on plans, ADRs, reviews, and workflows rather than the old case/claim dashboards.

Development and validation

Use per-run temporary fixtures or copied databases for tests. Never write test data or fabricated approvals into real projects. Repository instructions are in AGENTS.md, CLAUDE.md, and ISOLATION.md.

Private implementation records and operational logs are not distribution inputs. See apps/planner for isolated fixture modes. Native Claude mod-host rendering, live stochastic-provider acceptance, and packaged distribution remain separate validation work; a passing local source build does not establish those outcomes.

Release automation

Soundheart Studios maintains Planwright. Licensing contact: dev@soundheart.io. GitHub Actions validates pull requests and builds native Linux/macOS x64/arm64 archives on version tags. Archives include Node, production dependencies and third-party notices. Each extracted archive must pass isolated CLI/SQLite/HTTP smoke checks before a draft release is created for review. See release setup and targets.

Planwright is licensed under AGPL-3.0-only, with a commercial alternative available by separate signed agreement with Soundheart Studios. Contact dev@soundheart.io. Third-party components retain their own licenses; see third-party notices.