Phase Console

The whole plan library in one page.

phase-console                      # installed as a plugin, via npm or via brew — from anywhere
./start                            # cloned — from the folder
./start ~/code/your-repo           # skip the picker
./start --allow-writes             # plus the guarded write verbs
./start --allow-run                # plus the autopilot

cd ~/code/your-repo && phase-console start    # a console for THIS project
phase-console list                 # every console: name, root, port, status
phase-console open [<name>]        # open one in the browser
phase-console stop | restart | status | logs [-f]   [<name>]
phase-console install-skill        # copy the skill where Claude Code reads it

(First time on a machine: the client is built output — cd viewer && npm ci && npm run build, or let the console's own page tell you. As a background agent — deploy/agent.sh install|update, launchd on macOS, systemd on Linux — the install builds it for you.)

A plan library outgrows a terminal: dozens of plans, hundreds of phases, hundreds of handoff files — and the engine answers for exactly one plan at a time. The console is the portfolio view: what is ready right now across every plan, which lock is holding what, which plan has stalled, how much work is left, and whether a plan's graph even lints.

The console is eight destinations, a command palette, a bell drawer and a help sheet. Every older address still resolves — a bookmark, a handoff link or a push notification minted by an earlier version lands where its page went, keeping whichever half of the address still means something.

Riding on every page, on the query string rather than as pages of their own:

It updates itself: a watch on docs/ pushes changes over server-sent events, so a handoff written by an agent session appears without a reload.

More than one project

One install, one console per project. cd into a repository and start — it gets its own port, its own state and its own supervisor, and the consoles for your other projects keep running:

cd ~/code/alpha && phase-console start     # http://127.0.0.1:4123
cd ~/code/beta  && phase-console start     # http://127.0.0.1:4187 — a different console
phase-console list                         # both, with their roots and ports
phase-console open alpha                   # by name, from anywhere
phase-console restart beta                 # every verb takes the same selector

An instance is a repository root. Its identity is derived from the path, so it survives restarts and reboots without anything being written down: the same root is always the same console.

phase-console status with no selector reports all of them. Ports are reserved by registration rather than by being bound, so a stopped console still owns its port and a restart lands where it was — and starting a second console on a port that belongs to another project is refused, naming the project that owns it rather than failing with an address-in-use.

One rule governs the design. phase-graph.sh is the only source of truth for done / ready / waiting, session batches, boot prompts, QA regime and lint — the console shells out to those same scripts for every status claim and never recomputes it. JavaScript parsing covers only what the scripts do not expose (prose, phase detail, handoff bodies) plus analysis they do not provide (critical path, unblock value, velocity). A parity test re-derives every plan's board from that parse and asserts it matches the engine, so the two readings cannot drift apart unnoticed.

Writes are off by default. With --allow-writes the console can scaffold a plan or handoff, record a QA result, manage phase locks, and close or reopen a plan — each behind a dialog showing the exact command first. --git is never passed, so it can never commit or push. The server binds to 127.0.0.1, and keeps binding there even when you reach it from elsewhere — --remote puts an authenticating proxy in front of the loopback socket rather than opening one on a network.

Runs are off by default too, behind their own flag. --allow-run enables the autopilot: the console drives a plan unattended, one claude -p process per phase, so "clear the session between phases" needs no implementing — the process exits and takes its context with it. A phase advances only when three independent checks agree: the plan's own verification passes, validate.sh still passes, and the board re-read from disk says done. Nothing asks the session whether it succeeded. Model, effort and skills are chosen per run or per phase; a command that reaches outside the working tree raises an approval and waits for a person. It is a separate flag from --allow-writes on purpose: a write scaffolds a file, a run edits a repository for hours.

It runs on a phone. Watching a run and answering an approval are the two things that cannot wait until you are back at the desk, so the console can be driven from one — over your own private network, with nothing exposed to the internet. Setup: Reaching it from your phone.

Terminals outlive the console

A terminal is a process on this machine, not an object in a tab, and since 3.2 it is not a child of the console either. The ptys belong to a broker — one small detached process per console, addressed over a 0600 unix socket in the instance's own state directory — so restarting the console, or shutting it down on purpose, leaves every shell and every interactive claude running with its scrollback intact. A fresh console adopts what the last one left, and a URL that named a terminal still names it. Both the restart and the shutdown dialog read the real inventory and list what keeps running under "This keeps running", rather than claiming to stop what will not stop. A broker with no sessions left retires by itself, so nothing lingers once the last terminal ends.

Closing the browser was already safe — it detaches the socket and leaves the work running — and nothing is reaped for being idle. What changed is that the console going down is now safe too.

Every Claude session on this machine is one of these. The presence hook (scripts/session-hook.sh, Settings ▸ Automation ▸ Session presence, off until you install it) reports every claude running in a directory this console owns. Such a session belongs to a terminal the console does not hold, so it cannot be attached to — there is no multiplexer here — but it can be resumed: an ended one with a plain Resume, a live one with Take over behind a confirm that says a second claude joins the same conversation and the one you can see keeps running. Needs --allow-agent. The resume starts in the directory the registry recorded, not the console's root, because claude --resume resolves a conversation globally: from the wrong directory it does not fail, it succeeds in the wrong repository. A directory outside the open root and the recent ones takes a confirm that shows you the path first.

What a page costs

The console is a local server, so the cheapest thing it can do is not send bytes it does not need. Three habits, all of them invisible until you look for them:

Together those took a cold plan open on a large library from ~1,753 KB to ~442 KB on the wire, and took an 11.27 s wait on the plan validator off the read path entirely — the lint still arrives, as its own event, after the page is already drawn.

Details: viewer/README.md.

---