Install

You need Claude Code; the skill itself needs just Bash. The console additionally needs Node 22.18 or newer (or 23.6+) with npm. Run from a tree (Route A or B), it has a client that is built output: one npm ci && npm run build inside viewer/ per machine. You do not have to remember that: an unbuilt console serves a page naming the two commands and the exact directory to run them in.

Phase Console comes in three editions, all built from one source. This page installs each of them:

The package ships its client built, so it needs no npm run build, and its installer fetches Node when the machine has none.

Pick a route. Routes A and B give you the skill and the console from one tree, from the public repository. The free edition is not published as a package: the repository is the only channel, and a release is a tag on it — docs/releasing.md.

Route A — as a plugin (recommended: one line, updates itself)

A plugin is a package Claude Code installs for you. A marketplace is a catalog that lists plugins. This repository is both — it ships a catalog called phased-execution-public containing one plugin, itself. So installing is one command for each.

Step 1. Open Claude Code in any project and type:

/plugin marketplace add phased-execution-public/phase-console

Claude Code clones this repository, checks the catalog inside it, and remembers it as phased-execution-public. Nothing is installed yet — a marketplace is only a list.

Step 2. Install the plugin from that catalog:

/plugin install phased-execution@phased-execution-public

The @phased-execution-public part says which catalog to take it from. It matters once you have several registered.

Step 3. Load it:

/reload-plugins

Or just restart Claude Code. Type /plugin to confirm it is listed — that screen also has an Errors tab if something failed.

What you now have. The skill, as /phased-execution:phased-execution — Claude Code puts every plugin's skills under the plugin's name so two plugins can both ship a review skill without clashing. Type /phased and let autocomplete finish it. You will rarely type it at all: the skill describes itself well enough that Claude reaches for it on its own when work is phased. You also get phase-console, a command that starts the web app from any directory — the first run serves a page naming the client's one-time build (npm ci && npm run build, with the exact path printed, since a plugin lives in a cache directory you would otherwise have to hunt for).

Keeping it current. /plugin update phased-execution. This plugin sets no version number on purpose, which puts it on the commit channel: every push to main counts as a new release, and Claude Code also refreshes in the background. Restart to apply an update. An update moves the plugin to a fresh directory, so the console will ask for its build once more — same two commands, same printed path. (The tagged channel is the other way out: vX.Y.Z tags with a GitHub Release carrying the packed tarball, cut by hand — no registry and no CI. Same tree, two cadences — the plugin tracks every commit, the tags track releases, and each tag's notes are on the Releases page.)

Removing it. /plugin uninstall phased-execution@phased-execution-public, then optionally /plugin marketplace remove phased-execution-public.

Route B — as a plain folder (if you want to edit the skill, or script against its path)

git clone https://github.com/phased-execution-public/phase-console.git ~/.claude/skills/phased-execution

Restart Claude Code. The skill is /phased-execution — no prefix, because it is not inside a plugin. Build the console's client once (cd ~/.claude/skills/phased-execution/viewer && npm ci && npm run build), then start it with ~/.claude/skills/phased-execution/start. Update with git pull, then rebuild.

Running as a background agent? ./start --agent-update — or the app's own Restart — fetches the latest version, builds it, and restarts onto it; a failed build rolls back to the version it was.

Route C — Phase Console Pro, the prebuilt package (a license key, a login agent per project)

Pro is the phase-console-pro package: the whole console prebuilt — the client built, the server bundled — and unlocked by a license key, on up to three machines at a time. It needs Node 22.18 or newer (or 23.6+), and the hosted installer fetches one when the machine has none. There are three ways in, and each ends with the package installed and your key active on this machine.

The hosted installer takes it end to end. Run it in the folder of the project you want a console for, the one that holds docs/plans/:

curl -fsSL https://phase-console-site.vercel.app/install.sh | bash -s -- --key PCP-XXXX-XXXX-XXXX-XXXX

On Windows, in PowerShell, the same script runs inside WSL2:

iwr -UseBasicParsing https://phase-console-site.vercel.app/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File .\install.ps1 --key PCP-XXXX-XXXX-XXXX-XXXX

It takes four steps and skips each one that is already true:

1. Node. When yours is missing or older than 22.18, the official build from nodejs.org is checked against its published checksum and unpacked into ~/.local/share/phase-console/node.
2. The package. npm install -g phase-console-pro.
3. Your key. phase-console license activate, when you give it --key.
4. The login agent. For the project you run it in, written and started (launchd on macOS, systemd --user on Linux and WSL2), so that project's console comes up at every login. The agent is a Pro feature, so it follows the key: with no key this step is skipped, and the line to run later is printed.

The options are --version X.Y.Z, --prefix DIR, --root DIR (the project the agent serves, instead of the folder you are in), --port N, --minimal (start the console with none of its capability switches), --no-agent, and --dry-run, which prints each step and changes nothing. Its last lines are an undo block: the commands, last step first, that remove exactly what that run did — the agent, the activation, the package, the Node it unpacked and its receipt — each one a command the machine already has. They leave your projects and each console's state alone. Keep them: an install piped from the site (curl … | bash) has no other uninstaller. In a checkout, installer/uninstall.sh beside the script reads the receipt and runs the same steps. Details: installer/README.md.

npm installs the package, and you activate the key by hand:

npm install -g phase-console-pro
phase-console license activate PCP-XXXX-XXXX-XXXX-XXXX

Homebrew takes it from the tap:

brew install zsarir/tap/phase-console-pro
phase-console license activate PCP-XXXX-XXXX-XXXX-XXXX

Your key is in the email that came with your purchase, and on your account page. Activate it once per machine, from a terminal as above or in the console at Settings ▸ License, and every console on the machine is licensed. phase-console license status says what the machine holds. Without a key the package runs the free features, and the login agent is not set up until a key is active. The states, the weekly check, working offline and moving a key to another machine are in docs/license.md.

After the install, phase-console install-plugin makes the package Claude Code's plugin as well: the same skill, scripts and hooks a clone gives, from the copy npm or Homebrew installed. It re-points a marketplace of the same name, so it replaces Route A and does not add a second copy of the skill. Claude Code picks it up at its next start, or on /reload-plugins.

Updating is npm install -g phase-console-pro@latest, or brew upgrade phase-console-pro, then phase-console restart in each project. Your key stays active through an update. While the term runs every new version is yours; once it ends, a version released later needs a renewal (docs/license.md).

Removing it. Run phase-console license deactivate first, so the machine's place on the key is free for another machine, then npm uninstall -g phase-console-pro or brew uninstall phase-console-pro. An installer install is removed by the undo lines the installer printed when it was done, which do all of it; installer/uninstall.sh does the same from a checkout, and exists only there.

Route D — source access, a checkout of the private repository (every Pro surface, no key)

The source edition is a git checkout of the private repository, phased-console-pro/phased-execution, for use inside one organisation, under LICENSE-SOURCE-ACCESS.md. Source access is an optional tier, offered when the pricing page lists it: it adds read access to the repository, through an invitation to the GitHub account you name at checkout. A checkout runs every Pro surface and asks for no key. The console knows a source tree by two files the package never ships, free/manifest.json and scripts/build-free-tree.mjs, and Settings ▸ License reads Source checkout. From the clone, node bin/phase-console.mjs license status reads source.

git clone https://github.com/phased-console-pro/phased-execution.git ~/code/phased-execution

Then build and start it exactly as Route B does, from that folder in place of ~/.claude/skills/phased-execution. Updating is git pull, then rebuild.

A console copy inside a hub folder gets its own supervised console the same way — <hub>/phased-execution/ as a submodule, or <hub>/console/ as a plain clone, the shape the console is developed in. It installs its own agent with node bin/phase-console.mjs --install-agent --root <hub>.

Which route?

Plugin and clone at once works, but you would see the skill twice and pay its always-on cost twice — pick one of those two for the skill.

The other two editions:

The package registers itself as Claude Code's plugin with phase-console install-plugin, which takes the place of Route A. Use the package or the plugin for the skill, not both.

Linux, and Windows through WSL2

Every route above works on Linux exactly as written. The differences are below; there is no native Windows build, and on Windows the whole thing (Claude Code included) runs inside WSL2.

• The background agent is a systemd user service. phase-console --install-agent --root <repo> writes ~/.config/systemd/user/phase-console.service (Restart=always, same 150s stop grace as the launchd plist) and starts it — the app's own Restart and Shut-down buttons work the same as on macOS. It stops at logout unless you run loginctl enable-linger $USER once. Installing a console for a second project writes its own unit, phase-console-<id>.service, so the one you already have is never renamed; phase-console list prints which unit belongs to which project.

• On WSL, run it in a tmux window — WSL parks its VM when nothing runs in it, so the console is up whenever WSL is.

For a systemd --user unit, systemd must be on (it is on current WSL2 installs). If the install says so: add [boot] + systemd=true to /etc/wsl.conf, run wsl --shutdown from Windows, reopen. Until then — or instead — the tmux window above is the whole answer.

• The browser. On a Linux desktop the console opens via xdg-open. On WSL it hands the URL to Windows (wslview); if nothing can open one it prints the URL — WSL2 forwards localhost, so http://127.0.0.1:4123 in your Windows browser just works.
• The Terminal page (optional). Its native module (node-pty) has no Linux prebuilds, so npm compiles it during install if build tools exist — sudo apt-get install -y build-essential python3 first. Skipping this loses only the in-browser shell: board, writes, autopilot and agent sessions all run without it, and the Terminal page names exactly what is missing.

• To the license, each WSL2 distribution is a machine. A key is active on three machines at a time, and a distribution's own /etc/machine-id tells them apart, so two distributions on one PC count as two.
• The Desktop launcher below is macOS-only (a Finder .command file). On Linux the systemd agent is the equivalent — it is the supervised mode the launcher's SUPERVISED="yes" provides.

Give yourself a launcher (optional, macOS — the double-click way to a supervised console)

A double-click that starts the console. Started with SUPERVISED="yes" it installs a launchd agent, which is what makes the app's own Restart and Shut down buttons work — those exist only where a clean exit comes back, and a window you double-clicked is the server's parent, not its supervisor. Paste this into Claude Code:

Set up a Phase Console launcher on my Desktop.

1. Find the skill: whichever of ~/.claude, ~/.claude-a or ~/.claude-b contains
   skills/phased-execution/viewer/server/index.ts — or, for a plugin install, the
   phase-console directory under ~/.claude/plugins/.
2. Copy viewer/deploy/desktop-launcher.command from there to
   "~/Desktop/Phase Console.command", and make it executable. That one file
   starts any console registered on this machine — it asks which when there is
   more than one, and a copy named "Phase Console — <name>.command" always
   starts <name>. If no console has ever run here, have me start one for my
   repository first (phase-console start inside it, or <skill>/start <repo>).
3. Open the copy and walk me through the knobs at the top, one at a time:
     INSTANCE    leave blank — the file's name, or its menu, picks the console
     WRITES      --allow-writes: scaffold plans/handoffs, record QA, take locks, close plans
     RUNS        --allow-run: spawn unattended Claude sessions that edit the repository
     TERM_FLAG   --allow-terminal: a real shell in the browser, running as me
     AGENT       --allow-agent: interactive claude sessions + the New-plan wizard
     ACCOUNTS    --allow-accounts: register more than one Claude account and let a
                 run move to one with headroom (the usage meters work without it)
     MCP         --allow-mcp: register MCP servers and attach them to plans and
                 phases (reading the registry and its statuses works without it)
     WEBHOOKS    --allow-webhooks: POST announcements to URLs I register (Slack,
                 Discord, Telegram, my own relay) — the only door that sends
                 anything off this machine (reading the list works without it)
     SUPERVISED  leave "yes" — it installs a launchd agent, and that is what makes
                 the app's own Restart and Shut down buttons work
   Blank out any door I do not want opened, and explain any I am unsure about
   before changing it. There is no root, port or login to fill in: each
   console's root and port come from the registry, and remote access from the
   machine profile.
4. Then tell me to double-click it — do not run it yourself. Its first run can
   install a background agent that starts at login, and that is my call.

The Desktop file is a copy, not a link: updating the skill does not update it.
Re-copy it after an update — it prints a warning when it is older than the one
in the repo.

claude plugin marketplace add phased-execution-public/phase-console
claude plugin install phased-execution@phased-execution-public
claude plugin details phased-execution@phased-execution-public      # components + token cost
claude plugin update phased-execution
claude plugin uninstall phased-execution@phased-execution-public