Groundwork Console

The cockpit for Groundwork Kit fleets — the board (WORKSTREAMS/QUEUE/DONE/FACTS), the agent bus, live tmux panes, docs with change marks, roadmap actions, and ops — in one local web app. Single user, token auth, loopback by default.

Install & run

npm i -g agent-coord-mcp @davidbalzan/groundwork agent-coordination   # the kit (once)
npx @davidbalzan/groundwork-console                                    # or: npm i -g … && groundwork-console  (alias: gwc)

First run creates ~/.groundwork-console/config.json (add projects from Home → Add project) and ~/.groundwork-console/token, prints the URL and a sign-in link, and opens the browser already signed in. Everything runs on one port (:8790).

groundwork-console [start] [--port 8790] [--host 127.0.0.1 | --tailscale | --lan[=<ip>]] [--no-open] [--no-auth] [--config <file>]
groundwork-console doctor    # kit requires + which bins/paths were resolved
groundwork-console token     # print the token
groundwork-console config    # print the config path

Requires on the host: Node ≥ 22, tmux (pane monitor / spawn), and either the three kit bins above on PATH or a kit checkout at kitPath in the config. doctor tells you which it found. Console requires: seam ^0.1.0 · agent-coord-mcp ^0.24.0 · groundwork ^0.3.0 · agent-coordination ^0.5.0.

From another machine

groundwork-console --tailscale binds this machine's Tailscale IP (found via tailscale ip -4) instead of loopback and prints a sign-in link you can open from any device on your tailnet; the token cookie does the rest (plain http — keep it on the tailnet, or put TLS in front). On the same home network without Tailscale: groundwork-console --lan binds the primary private LAN IPv4 (or --lan=<ip> to pin one) — same sign-in link flow, plain http, trusted networks only. Otherwise: ssh -N -L 8790:127.0.0.1:8790 <host> and open http://localhost:8790. --no-auth is refused together with --lan/--tailscale (token auth must front any non-loopback bind).

What it does

• Home — what needs you (DAVID_DECISION packets with age), fleet presence per project, roadmap strips.
• Board — active streams, queue, done, facts, phases with Plan / Kick off / Audit (DMs to the aide/coordinator), project doctor with Fix → agent.
• Bus — rooms, inbox, status stream, prefix chips, decision packets; replies mark packets answered.
• Monitor — live read-only tmux panes per agent, role colours, the "Now" widget (phase · streams → owners), pop-out with the phase task list.
• Docs — project docs and the global knowledge repo (ADRs, notes) with git change marks; edit non-seam docs in place.
• Summon — bottom-right avatar: DM any agent from any page with the page/doc as context, paste images.
• Ops — fleets (spawn / unregister / prune / decommission), skills, release, runs, events.

Writes are behind two one-click header switches (bus writes · seam & docs writes); with both off the console cannot change disk or bus. Seam files are only ever written through the seam (byte-identical round-trip); the console never types into panes — messages go through the bus and each agent's own pusher.

Config & env

~/.groundwork-console/config.json: { "kitPath": "~/workspace/groundwork-kit", "coordDir": "~/agent-coord", "projects": [{ "name", "path", "room" }] }. Env: GROUNDWORK_CONSOLE_HOST (bind; default 127.0.0.1 — put the token auth in front before exposing), GROUNDWORK_CONSOLE_TOKEN, GROUNDWORK_CONSOLE_UPLOAD_TTL_HOURS (pasted images are purged after this many hours; default 6), GROUNDWORK_CONSOLE_AUTH=off, GROUNDWORK_CONSOLE_CONFIG, GROUNDWORK_CONSOLE_RULES, AGENT_COORD_DIR, PORT. (KIT_CONSOLE_* from the pre-rename days is still honoured.)

Source, issues, design notes: https://github.com/davidbalzan/groundwork-console. MIT.