Skip to content

About

See it before it's built. Any terminal coding agent sketches screens, architecture and plans on a whiteboard you mark up, then builds in its own git worktree.

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

 

History

3,942 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Glimmervoid

CI License: MIT Node.js Platform: Windows | Linux | macOS

See it before it's built. Your coding agent sketches the screen, draws the architecture and shows you on a whiteboard.

glimmervoid.dev

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.

Glimmervoid dashboard replaying recorded Claude Code sessions: one fixes a flaky upload test with its diff in the terminal, three more work on their own projects in the session rail

Quickstart

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
glimmervoid

Windows (PowerShell):

powershell -c "irm https://github.com/johncwaters/glimmervoid/releases/latest/download/glimmervoid-installer.ps1 | iex"
glimmervoid

Homebrew:

brew install johncwaters/tap/glimmervoid
glimmervoid

The 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.

From source

git clone https://github.com/johncwaters/glimmervoid.git
cd glimmervoid
npm ci
npm run build
npm start

npm 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.

Requirements

  • 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 node on 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.

Supported agents

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.

Features

  • 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+J jumps 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, .m4a or .webm files 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 --hard and git push --force and reads of credentials such as SSH keys and .env files. 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.

Keyboard

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

Commands

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.

Configuration

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.

How status detection works

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:

  • /clear looked 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 Stop fired 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 own background_tasks field, 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

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.

  1. Add a remote block to ~/.glimmervoid/config.json. publicHost is the hostname your proxy serves:

    {
      "remote": { "port": 3456, "publicHost": "my-machine.example.ts.net" }
    }
  2. Restart Glimmervoid. The log shows Glimmervoid remote listener on http://127.0.0.1:3456 (paired devices only).

  3. Point an HTTPS reverse proxy at that port. With Tailscale, tailscale serve --bg 3456 serves https://<machine>.<tailnet>.ts.net, which is what publicHost should hold.

  4. From the device, open https://<publicHost>/. You should see Glimmervoid's "Pairing required" page.

  5. On the host, run glimmervoid pair --name phone and 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.

Running as a service (Linux)

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.target
systemctl --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.

Security

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.

Contributing

See CONTRIBUTING.md. Release history is in CHANGELOG.md.

License

MIT

About

See it before it's built. Any terminal coding agent sketches screens, architecture and plans on a whiteboard you mark up, then builds in its own git worktree.

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages