See it before it's built. Your coding agent sketches the screen, draws the architecture and shows you on a whiteboard.
Glimmervoid takes a feature from start to finish. Every agent works in its own git worktree, status comes from the agent's own hooks, and the one session that needs you comes to the front. Review and merge from the same page.
It is an orchestrator, not a harness. Your coding agents run unmodified, as real processes in real terminals on your own machine, with your own login, subscription, skills, hooks and settings, talking straight to their model. No cloud service, no account. Glimmervoid is developed inside Glimmervoid.
1. Install and start it. The standalone binary needs no Node. Linux and macOS:
curl -LsSf https://github.com/johncwaters/glimmervoid/releases/latest/download/glimmervoid-installer.sh | sh
glimmervoidWindows (PowerShell):
powershell -c "irm https://github.com/johncwaters/glimmervoid/releases/latest/download/glimmervoid-installer.ps1 | iex"
glimmervoidHomebrew:
brew install johncwaters/tap/glimmervoid
glimmervoidThe curl and PowerShell installers put glimmervoid and its updater glimmervoid-update in ~/.glimmervoid/bin and add that folder to your PATH; open a new terminal if glimmervoid is not found yet. Homebrew keeps it in its own folder and updates it with brew upgrade glimmervoid.
Glimmervoid is no longer published to npm; 0.54.0 was the last npm release. An npm or npx install switches over from the dashboard: open Settings, Updates and press Update.
2. Open http://localhost:3000. The first start from a terminal opens it in your browser for you; pass --no-open to skip that.
The first start puts a Glimmervoid icon on your desktop. Double-clicking it opens the dashboard, starting Glimmervoid in the background first when it is not running, so after that you never need a terminal; shut it down from Settings when you are done. Deleted the icon? glimmervoid shortcut puts it back.
3. Follow the checklist. The empty dashboard walks you through three steps: an agent CLI it can find, the folder that holds your git checkouts, and your first session. It suggests folders such as ~/Projects that already hold git repos, or you can type a path. Each subfolder becomes a project. For a folder outside your repository roots, open Run in a folder outside your repository roots in the + Session dialog.
That is the whole setup. Allow notifications when the dashboard asks, and keep a dashboard tab open: a notification appears whenever that tab is in the background.
If something fails, run glimmervoid doctor and see troubleshooting.
git clone https://github.com/johncwaters/glimmervoid.git
cd glimmervoid
npm ci
npm run build
npm startnpm ci does not run on Windows, because a dev dependency supports only macOS and Linux: on Windows, use the standalone binary or build from source in WSL.
To update, run git pull --ff-only && npm ci && npm run build and restart. The dashboard's update banner shows the right command for however you installed.
- Node.js 24.15 or newer, only for a source build; the standalone binary carries its own. Distro-packaged Node is usually older; use nvm, NodeSource or the official installer. Coherence, when a repository uses it, runs with the
nodeon your PATH. - Windows 11, Linux or macOS. CI runs the suite on Linux and installs and starts the package on Windows; macOS is tested by hand.
- An agent CLI on PATH: Claude Code, Codex, Kimi Code, OpenCode, pi, Grok or another terminal agent.
- git on PATH, for per-session worktrees.
glimmervoid doctor checks all of these.
| Agent | Command | Status from |
|---|---|---|
| Claude Code (default) | claude |
Hooks |
| Codex CLI | codex |
Hooks, plus its session log for a plan awaiting approval |
| Kimi Code | kimi |
Hooks |
| OpenCode | opencode |
A plugin Glimmervoid generates for each session |
| pi | pi |
An extension Glimmervoid generates, which also asks before shell commands and file edits |
| Grok Build (best effort) | grok |
Hooks, after running glimmervoid agent setup grok once |
| Any other terminal agent (best effort) | your own | Terminal title only |
Claude Code, Codex, Kimi Code, OpenCode and pi are first-class: every feature is checked against live recordings of each, so a waiting prompt, a plan, a question, compaction, sub-agents and /clear look the same on each card.
Declare another agent under customAgents in config.json with an id, label and command, plus optional args, idleTitle and busyTitle. The + Session dialog offers only the agents it finds on PATH, and a project can default to one with projects[].agent.
- Focus view. A rail of every session on the left, the selected session's live terminal in the middle, its changes on the right. The top of the rail counts what needs you, and
Cmd/Alt+Jjumps straight to the next one from any tab. - A worktree per agent. Every session in a git repo gets its own worktree, so agents never step on your checkout or each other. Review the diff and merge with one click while the agent keeps working. A conflicted merge parks, and Resolve in session hands it back to the agent that wrote it.
- Exact status. Hooks report every state change and the terminal title fills the gaps. The screen is never scraped (how).
- Notifications. Browser notifications when a session needs input, finishes or fails, with your own alert sounds if you like (drop
.ogg,.mp3,.wav,.m4aor.webmfiles into~/.glimmervoid/sounds/). Telegram covers you when no dashboard is open. - Phone layout. Board, terminal and review screens, attention first, with a terminal that resizes around the keyboard.
- Sane YOLO. It runs in every session and lane whose agent supports it, refusing commands like
git reset --hardandgit push --forceand reads of credentials such as SSH keys and.envfiles. It catches accidents; it is not a sandbox. - Usage. Tokens and estimated cost from local Claude Code, Codex, Kimi Code and Grok transcripts, with optional budgets.
- Auto-resume. Sessions live when Glimmervoid stopped come back with their conversation resumed.
- Remote access (opt-in). Reach the dashboard from another device through single-use pairing links.
- Radar (opt-in). Watches PostHog error tracking, pings Telegram on a spike, regression or new issue, and sends an agent to investigate. Optional auto-fix leaves a local branch; a pull request opens only after you approve it.
- Team PR review (opt-in). Drafts a review of each open pull request from a GitHub team in a guarded agent, optionally with your own review skill. Nothing posts until you choose Approve or Comment.
Cmd on a Mac, Alt elsewhere:
| Keys | Action |
|---|---|
Cmd/Alt+J |
Next session that needs you |
Cmd/Alt+1 to 9 |
Jump to a session |
Cmd/Alt+Up / Down |
Move through the rail |
Cmd/Alt+U |
Resolve a parked merge, or resync the base branch |
Cmd/Alt+0 |
Add a session |
glimmervoid # start the server on port 3000
glimmervoid --port 3001 # start on another port
glimmervoid doctor # check the install, PATH, agents and native module
glimmervoid settings list # read and change settings from the terminal
glimmervoid pair --name phone # pair a remote device
glimmervoid --help lists every command.
Glimmervoid creates ~/.glimmervoid/config.json on first run. Most settings live in the dashboard's Settings view; the rest you can change with glimmervoid settings or by editing the file, which the server reloads on save. Every key, default and environment variable is in the configuration reference, generated from the code.
Worktrees branch from each repo's default branch (origin/HEAD, then main, then master) unless you set worktree.integrationBranch.
Glimmervoid sends anonymous usage and error data by default. Telemetry lists exactly what is sent and how to turn it off.
The obvious way to tell whether an agent is working, waiting or done is to scrape the terminal for a prompt or a spinner. That breaks on every redraw, theme change and CLI release, so Glimmervoid never does it.
Instead, each session gets agent hooks scoped to that one session, with no change to your repo. They POST every lifecycle event to a local endpoint: prompt submitted, turn stopped, notification raised, sub-agent started or finished. Hooks are the authoritative signal. The terminal title (spinner glyph means working, idle glyph means ready) covers anything the hooks miss, and a hook wins any conflict.
Three bugs shaped the details:
/clearlooked like a finished turn. It fires no hooks but flashes a spinner, then an idle glyph, in the title, so early builds sent "session complete" on every clear. Now a clear or compact resets both signals and mutes the title until the next real prompt.- A background sub-agent outlived its parent's turn. The main agent's
Stopfired while a sub-agent was still working. Now a session stays out of Complete until the live sub-agent count, reconciled against Claude Code's ownbackground_tasksfield, reaches zero. - Auto-resume silently never ran. It waited for
SessionStart, which Claude Code does not reliably fire on interactive startup. Now the conversation id comes from whichever hook arrives first.
Every session writes a JSONL recording of hook payloads and state transitions (never terminal bytes), and a replay harness runs recorded sessions back through the detection code as regression tests.
Remote access is a second listener on 127.0.0.1, always on and answering paired devices only, that you put behind an HTTPS reverse proxy; Glimmervoid never binds a wider address unless GLIMMERVOID_INSECURE_BIND=1 is set. Without remote.port it takes a free port the system picks, so set remote.port for a proxy to point at.
-
Add a
remoteblock to~/.glimmervoid/config.json.publicHostis the hostname your proxy serves:{ "remote": { "port": 3456, "publicHost": "my-machine.example.ts.net" } } -
Restart Glimmervoid. The log shows
Glimmervoid remote listener on http://127.0.0.1:3456 (paired devices only). -
Point an HTTPS reverse proxy at that port. With Tailscale,
tailscale serve --bg 3456serveshttps://<machine>.<tailnet>.ts.net, which is whatpublicHostshould hold. -
From the device, open
https://<publicHost>/. You should see Glimmervoid's "Pairing required" page. -
On the host, run
glimmervoid pair --name phoneand open the printed link on the device. It is single-use and expires in 10 minutes.
glimmervoid pair --list shows paired devices, and glimmervoid pair --revoke <id> removes one without a restart.
A paired device has full control of the machine as your account, so treat pairing links like passwords. Behind HTTP-mode tailscale serve, you can also set "ownerLogin": "you@example.com" in the remote block so only that Tailscale login gets through, on top of pairing. Only HTTP-mode tailscale serve strips a forged Tailscale-User-Login header; behind any other proxy, or tailscale serve --tcp or --tls-terminated-tcp, ownerLogin proves nothing.
A systemd user unit keeps Glimmervoid running after you log out:
# ~/.config/systemd/user/glimmervoid.service
[Unit]
Description=Glimmervoid
[Service]
ExecStart=/usr/bin/env glimmervoid
EnvironmentFile=-%h/.glimmervoid/secrets.env
Restart=on-failure
[Install]
WantedBy=default.targetsystemctl --user daemon-reload
systemctl --user enable --now glimmervoid
loginctl enable-linger "$USER"The unit's PATH must reach node, glimmervoid and your agent CLIs. With nvm, set Environment=PATH=... or use absolute paths in ExecStart. For a source checkout, use ExecStart=/usr/bin/env node dist/server/index.js with WorkingDirectory= set to the checkout.
secrets.env is optional. Put GLIMMERVOID_POSTHOG_API_KEY and GLIMMERVOID_TELEGRAM_BOT_TOKEN there to keep them out of config.json.
Glimmervoid runs agents with your account's privileges. The local dashboard has no login and binds only 127.0.0.1 unless GLIMMERVOID_INSECURE_BIND=1 is set, so any local process can drive it and the port must never be exposed to the network. Use remote access to reach it from elsewhere.
SECURITY.md has the full trust model and how to report a vulnerability privately.
See CONTRIBUTING.md. Release history is in CHANGELOG.md.
