grok-glance

A Grok Build plugin that puts a small web dashboard behind a passkey, so you can glance at what your agents are doing from your phone — and tap approve or deny when one wants to run something risky. Several agents at once is the normal case, not an edge case.

It is deliberately small: read-only, plus remote approve/deny. It cannot send prompts, edit files, or drive a session.

┌────────────────────────────┐
│ ● grok-glance  2 working ·│
│                 1 waiting  │
├────────────────────────────┤
│  Waiting on you      62s   │
│  Bash · in ●2 remote-grok  │
│  rm -rf ./dist             │
│  ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░   │
│  [   Deny   ] [  Approve ] │
├────────────────────────────┤
│  Agents            3 live  │
│  All agents             3  │
│  ●1 remote-grok   working  │
│     Read 4s state.ts  +2   │
│     31 tools         now   │
│  ●2 remote-grok   waiting  │
│     Bash 1m  rm -rf ./dist │
│     12 tools  1 failed 4s  │
│  ●3 docs-site       error  │
│     build failed      2m   │
├────────────────────────────┤
│  Activity                  │
│  ● Read state.ts ●1 14:22  │
│  ● Bash npm test ●3 14:21  │
└────────────────────────────┘

Requirements

• Node.js 20 or newer. npm is only needed to develop it — dist/ is committed, and the daemon bundle carries its one runtime dependency inside it, so an installed copy never runs a build or an install step.
• Grok Build.
• For phone access: Tailscale on both the machine and the phone. See Why Tailscale — a LAN IP genuinely cannot work.

Install

Grok Build loads plugins straight out of ~/.grok/plugins/, so the shortest install is a clone:

git clone <this repo> ~/.grok/plugins/grok-glance

That is the whole thing — no npm install, no build. Open /plugins in Grok Build and enable grok-glance. The first hook to fire after that — your next prompt, or the first tool call — starts the daemon in the background, and the dashboard is on http://127.0.0.1:8791. (Not the SessionStart hook, which for a plugin never runs; see Hook wiring.)

…or from a marketplace, by URL

If you would rather install it the way marketplace plugins are installed — or point several machines at one URL — this repo is also its own one-entry marketplace: .grok-plugin/marketplace.json lists exactly one plugin, sourced from ./, which is the repo root the catalog itself lives in. So the repo's git URL is a complete marketplace, with no commit SHA to pin (a self-referencing remote source would have to pin the SHA of the commit that contains the pin).

Add it as a marketplace source from the TUI — /plugins, Marketplace tab — or from the CLI:

grok plugin marketplace add https://your-git-host/you/grok-glance.git
grok plugin install grok-glance --trust

Configured sources are recorded in ~/.grok/config.toml under [[marketplace.sources]] and in ~/.grok/plugins/known_marketplaces.json; the TUI and grok plugin marketplace list read the same list. Check grok plugin marketplace --help if the subcommand names have moved — the clone above does not depend on any of this.

Why there is no build step

dist/ is checked in:

• dist/server/index.js — the daemon, bundled to a single dependency-free ESM file. Its only runtime dependency, @simplewebauthn/server, is inlined; everything else it uses is the Node standard library. It is not minified, so what ships is what you can read.
• dist/web/ — the dashboard, already a static bundle, which the daemon serves itself.

The hook scripts under bin/ were stdlib-only from the start. So a clone has nothing to resolve and nothing to compile, which is what makes a bare git URL enough.

Working on it instead? Then you do need the toolchain:

npm install
npm run build        # tsc typechecks, rolldown bundles the server, vite builds the web app
npm run check:dist   # rebuilds and fails if the committed dist/ is stale

hooks/hooks.json is checked in as-is — nothing about it is generated or machine-specific. The shared secret the hook scripts authenticate with lives in ~/.grok/glance/hook.secret (mode 0600) and is created by the daemon on first start; it never appears in hooks.json.

Get it onto your phone

The daemon binds to 127.0.0.1 only and never opens a port to your network. Tailscale Serve publishes it inside your tailnet with real TLS:

tailscale serve --bg 127.0.0.1:8791
tailscale serve status     # note the https://<box>.<tailnet>.ts.net URL

Tell grok-glance which origin it is being served on — this is also the WebAuthn relying-party ID, so it has to be exact:

node bin/glance set-origin https://<box>.<tailnet>.ts.net

Enrol the phone

node bin/glance enroll

That prints a URL and an 8-character code, good for 10 minutes, single use:

  Open this on your phone:

    https://mybox.tailnet-1234.ts.net/?enroll

  Enrollment code:  K7QM4RTX
  Valid for:        10 minutes (single use)

Open the URL on the phone, type the code, tap Create passkey, and confirm with Face ID / a fingerprint / the device PIN. From then on the phone unlocks the dashboard with that passkey and nothing else gets in.

Repeat for each device you want. node bin/glance devices lists them; node bin/glance revoke <id-prefix> removes one (and kills its live session immediately).

What the dashboard shows

• Agents — one row per agent whenever there is more than one: badge, workspace, state, what it is running right now, and how long ago it last did anything. Tap one to focus it; tap All agents to come back. Ended sessions are folded away behind a toggle.
• Now — the focused agent: its workspace, state (working / waiting on you / idle / error / ended), the last thing you asked, every tool it currently has in flight with a live elapsed timer each, and running counts of tools, failures and denials.
• Activity — a merged timeline of prompts, tool calls with durations, failures, permission denials, notifications, subagents, compactions, session start/end. Each row is stamped with the badge of the agent it came from; focusing an agent filters it down to that one.
• Pending approvals — a card per waiting tool call, with the command, which agent is asking, a countdown, and two large buttons.

Updates arrive over Server-Sent Events. The server sends whole snapshots rather than deltas, so a phone that slept through twenty events still wakes up showing the truth.

Several agents at once

Watching four agents on a phone is a different problem from watching one, so a few things are not what you might assume:

• Badges, not names. Labels are workspace basenames, so two agents in the same repo are both "remote-grok". The daemon hands each session a small ordinal in arrival order — ●1, ●2 — and the dashboard colours everything belonging to that agent with it: its row, its timeline lines, its approval cards. The ordinal survives a daemon restart.
• Sorted by who needs you, then fixed. Rows are ordered waiting → error → working → idle → ended, and ties break on badge. Within a state an agent never changes position, because a list that re-sorts on every event moves the row out from under a thumb already heading for it.
• A chatty agent cannot bury the others. The event ring is global, but eviction always takes from whichever session currently holds the most of it. One agent in a tight loop trims itself rather than blanking everyone else's history.
• Parallel tool calls are all shown. An agent runs several tools at once; the focused card lists them and the overview row shows the first with a +2. Durations are matched oldest-first per tool name, since hook payloads carry no call id.
• A restart does not lose the roster. Events carry no workspace root, so the session map is persisted separately (sessions.json) and reloaded on boot — otherwise every agent would come back nameless until it happened to speak again. In-flight tools are deliberately not restored: they belonged to a process that no longer exists.

glance status shows the same breakdown from a terminal:

  sessions      : 4 (1 waiting on you, 1 error, 2 working)

Remote approve / deny

Off by default. Turn it on from the phone's settings panel, or:

node bin/glance approval risky     # Bash, Write, Edit, MultiEdit, NotebookEdit
node bin/glance approval all       # every tool call — noisy
node bin/glance approval off

Defaults worth knowing:

Behaviour	Default	Changeable from the phone	Why
Only wait when a phone is watching	on	yes	Otherwise a closed browser tab stalls the agent for 90s per tool call.
On timeout	allow	yes	Flip to deny if you would rather fail closed.
Timeout	90s	no — edit config.json	Also the ceiling: the approval hook gets 125s in hooks.json, and the daemon clamps a larger timeoutMs down to 90s so the script always outlives its own wait.
Risky-tool pattern	^(Bash|Write|Edit|MultiEdit|NotebookEdit)$	no — edit config.json	Shown on the phone but not editable: a typo'd regex would silently change what gets gated.

This is a convenience gate, not a security boundary. Every failure path is fail-open: daemon down, hook timeout, malformed response, port mismatch, a hook secret the daemon no longer recognises — the tool call proceeds. If you need calls actually blocked, use Grok Build's own permission settings.

CLI

bin/glance is plain Node with no dependencies. Run it as node bin/glance <command>.

Command	What it does
status	Running? On which origin, with how many devices?
up	Start the daemon in the background
serve	Run it in the foreground (for debugging)
stop	Stop it
logs	Last 60 lines of the daemon log
enroll	Mint a one-time enrolment code and URL
set-origin <url>	Set the public https origin and RP ID
devices	List enrolled devices
revoke <id-prefix>	Revoke a device
approval <off|risky|all>	Set the approval policy

Files and configuration

Everything lives in ~/.grok/glance (mode 0700), or $GLANCE_HOME if you set it:

File	Contents
config.json	Port, bind host, public origin, RP ID, approval settings
credentials.json	Enrolled passkeys — credential IDs, public keys, counters. No secrets of yours.
auth-sessions.json	Live dashboard sessions, stored as SHA-256 hashes of the cookie tokens
secret.key	32-byte HMAC key used to sign session cookies
admin.token	Rotated every daemon start; authenticates the CLI
hook.secret	Shared secret the hook scripts present on /hook/*. Created once, mode 0600, never rotated — a rotation mid-session would 403 whatever was already in flight. Delete it and the daemon mints a new one on its next start; hooks then need that restart to agree again, which glance status will tell you about.
events.jsonl	Append-only event log, one JSON object per line, rotated at 5 MB
sessions.json	The agent roster — label, badge, workspace, state, counts — so a restart comes back with the overview intact. Written debounced, flushed on shutdown; sessions older than 12 hours are dropped on load.
daemon.log	Daemon stdout/stderr
daemon.lock	Held while a hook script is starting the daemon, so a burst of events starts one and not five. Created with O_EXCL, deleted on the way out, and ignored by anyone else once 15s stale.

Three environment variables override config.json, which is mostly useful for testing a second instance without touching your real one:

Variable	Effect
GLANCE_HOME	Where all of the above lives. Read by the daemon, the CLI, and the hook scripts.
GLANCE_PORT	Port to listen on (and, for the CLI and hooks, to talk to)
GLANCE_ORIGIN	Public origin, as if set with set-origin — but not persisted

Nothing in hooks/hooks.json is machine-specific: the hook scripts read config.json themselves, so changing the port or approval.timeoutMs needs nothing but a daemon restart.

Security notes

Network surface. The daemon listens on 127.0.0.1:8791 and makes no outbound connections of its own. Three classes of caller:

Path	Caller	Authentication
/hook/record, /hook/approve	Grok Build's hooks, from this machine	shared secret from hook.secret, plus a refusal of any proxied request
/api/*, /events	the dashboard	passkey session cookie + CSRF header
/local/*	the glance CLI	rotating admin token from admin.token

None of the three trusts the source address, because tailscale serve proxies remote traffic to 127.0.0.1 — the daemon cannot tell a local caller from a tunnelled one by address alone. Without the hook secret, anyone who could reach the tunnel could forge timeline events and answer approval prompts on your behalf; /hook/* compares the secret in constant time before it reads a body, and additionally refuses any request carrying x-forwarded-for or x-forwarded-proto, which a local hook process never sends and a tunnelled caller always does.

That refusal costs nothing, because no legitimate hook traffic comes through the tunnel: hooks are local processes talking to loopback. It applies only to /hook/* — the dashboard arrives through tailscale serve with those headers on every request and is unaffected.

Session cookie is HttpOnly, SameSite=Strict, HMAC-signed, and Secure whenever the request arrived over https. Only a SHA-256 hash of the token is stored, compared in constant time. Sessions last 30 days; revoking a device drops its session at once.

Cross-site defence. Every POST must carry exactly content-type: application/json, which is not a CORS-safelisted type, so a hostile page cannot post here without a preflight that is never answered. /api/* additionally requires an x-glance-csrf header. The pages themselves are served with a strict CSP (script-src 'self', no framing, no form actions) and no-store.

User verification is required, for both enrolment and sign-in: the phone asks for a biometric or PIN every time, so a stolen unlocked phone is not automatically a way in. Passkeys are created as resident keys, so the phone offers the right one without you typing a username.

Rate limits. Authentication attempts are capped (40 per 5 minutes), enrolment attempts more tightly (12 per 5 minutes, and a code burns itself after 5 wrong guesses). The limiter is keyed globally on purpose: behind a tunnel every request arrives from 127.0.0.1, so per-IP buckets would be one bucket wearing a hat.

What crosses the wire. Tool names, truncated arguments, prompt first lines, file paths, durations, and exit statuses — a summary, not a transcript. Known secret shapes are redacted before storage: sk-/rk-/pk- keys, xai- keys, GitHub and Slack tokens, AWS access key IDs, JWTs, PEM private-key blocks, Authorization:/Bearer headers, and password/secret/token/api_key assignments. This is a filter, not a guarantee — a secret in an unusual shape will show up in the timeline. Treat the dashboard as being as sensitive as your terminal.

Threat model. grok-glance assumes the machine it runs on is trusted. It protects against someone else on your tailnet, or a browser tab you left open, reaching the dashboard. It does not protect against a local attacker who can read ~/.grok/glance — with admin.token they can enrol their own device.

Why Tailscale, and not just the LAN IP?

WebAuthn will not run outside a secure context, and — separately — a bare IP address cannot be a relying-party ID. So http://192.168.1.20:8791 can never hold a passkey, no matter what the browser is willing to render. You need a hostname with valid TLS. Tailscale Serve gives you one for free, with the tunnel closed to everything outside your tailnet.

Any other route to a real https hostname works too: set origin in config.json (or use set-origin) to whatever your reverse proxy terminates on. If you put grok-glance behind a proxy reachable from the public internet, the passkey gate is the only thing standing in front of it.

Changing the origin changes the RP ID, and passkeys are bound to the RP ID — existing devices stop working and must be enrolled again.

Hook wiring

hooks/hooks.json subscribes to all 14 lifecycle events and is a plain checked-in file — edit it directly.

Every entry is a command hook. That is not a style choice: an http hook cannot reach this daemon by any route. Grok Build's http runner rejects every scheme but https, then resolves the host and refuses the resolved address if it is private, link-local or CGNAT (xai-grok-hooks/src/runner/http.rs, validate_hook_url + is_blocked_ip). Plain http on loopback fails the scheme check; the tailnet fails the address check, because *.ts.net resolves into 100.64/10 (and fd7a::/48, inside the blocked fc00::/7). On top of that the runner sends no request header but Content-Type, with no configuration surface for one, so such a hook could not authenticate itself even if it could connect. This plugin shipped http hooks for a while, and the result was 13 passive hooks failing validation silently on every event.

A command hook has none of those problems. It is a local process, so no URL is validated, nothing traverses the tunnel, and it can present the shared secret — hook traffic goes straight to http://127.0.0.1:8791 and never leaves the machine. So each observed event runs bin/glance-record.mjs, which costs a Node start (~40 ms) and POSTs one event. Two entries differ:

• SessionStart runs bin/glance-up.mjs. It is the obvious hook to boot the daemon from, and it never runs — see below.
• PreToolUse is wired twice — a recording entry for the timeline, and a second entry matching only ^(Bash|Write|Edit|MultiEdit|NotebookEdit)$ that runs bin/glance-approve.mjs. PreToolUse is the only blocking event, and a command hook is the only documented way to return a deny decision; keeping the match narrow means the gate's cost is paid only for calls that could actually need a tap. Its timeout is a fixed 125s, and the daemon clamps its own wait to 90s against it (APPROVAL_MAX_WAIT_MS) so the script is never killed before it can fail open.

The hook scripts use nothing but the Node standard library and always exit 0 unless they are deliberately denying — including when the daemon rejects their token.

Why every recorder boots the daemon

A plugin gets no usable boot event, so bin/glance-record.mjs starts the daemon itself when it finds it missing, and whichever event fires first wins.

SessionStart looks like the right answer and cannot work. Grok Build dispatches it from inside session creation (xai-grok-shell, agent_ops.rs → SessionCommand::DispatchSessionStartHook), and the dispatch resolves against the session's hook registry as it stands at that moment. That registry comes from discover_hooks(), whose sources are the config layers and the global/project settings files — ~/.grok/settings.json, <git_root>/.grok/hooks, the vendor-compat paths. Plugin directories are not among them. Plugin hooks are appended separately, under a plugin/ prefix, by reload_hooks_impl and reload_plugins_impl — both of which run later, in response to a plugin action, a /hooks reload, or a folder-trust grant. So a plugin's SessionStart entry is always registered after SessionStart has already been dispatched, and is never called. Every other event this plugin subscribes to happens later in the session, once the plugin registry has landed, which is why they all work.

The symptom, if you hit this from the other end: no daemon.log at all, nothing on :8791, and a manual glance up working perfectly.

Asking costs one loopback request to /healthz per event, which is the steady state once the daemon is up. The spawn path is taken once. A daemon.lock (O_EXCL, 15s staleness) keeps a burst of concurrent events from starting five daemons and leaving four of them to die on EADDRINUSE.

Deliberately omitted

Not oversights — decisions:

• Sending prompts or steering the session. Hooks cannot inject input, so a phone-to-agent channel would need a second transport and a much larger threat model.
• Full transcripts and tool output. Summaries only. Streaming assistant text through a phone would mean shipping your codebase through it.
• Push notifications. Needs a VAPID key, a service worker, and a subscription store, for a dashboard you open on purpose.
• Multi-user accounts and roles. One user, several devices.
• Diff views, file browsing, cost/token charts, log search, session resume. All out of scope for a glance.
• Editing the risky-tool pattern from the phone. Shown but not editable: a typo'd regex there would silently change what gets gated. Edit config.json instead.

Licence

MIT.