first commit

2026-08-09 04:00:13 +00:00
commit b3b6bf3f70
46 changed files with 7146 additions and 0 deletions
@@ -0,0 +1,83 @@
+---
+name: glance
+description: Set up, inspect, or control grok-glance — the passkey-guarded phone dashboard for this Grok Build session. Use when the user asks to watch a session from their phone, enrol a device, expose the dashboard over Tailscale, or turn remote approve/deny on or off.
+---
+
+# grok-glance
+
+A local daemon plus web dashboard that shows what Grok Build is doing, readable from a phone
+behind a WebAuthn passkey. It can also pause risky tool calls until someone taps approve.
+
+The daemon is started automatically by the `SessionStart` hook. Everything below is done through
+the `glance` CLI at `$GROK_PLUGIN_ROOT/bin/glance`.
+
+## First check whether it is even built
+
+The plugin ships as TypeScript and must be built once:
+
+```sh
+cd "$GROK_PLUGIN_ROOT" && npm install && npm run build
+```
+
+`glance status` prints a "not built" error with this same instruction if it is missing. Do not
+attempt to skip the build — the daemon entry point is `dist/server/index.js`.
+
+## The commands
+
+```sh
+glance status                      # is it running, which origin, how many devices
+glance up                          # start the daemon in the background
+glance stop                        # stop it
+glance logs                        # last 60 lines of the daemon log
+glance enroll                      # mint a one-time code + URL for a new phone
+glance set-origin <https-url>      # set the public origin and WebAuthn RP ID
+glance devices                     # list enrolled devices
+glance revoke <id-prefix>          # revoke one
+glance approval <off|risky|all>    # remote approve/deny policy
+glance sync-hooks                  # rewrite hook URLs after changing the port
+```
+
+## Getting it onto a phone
+
+The dashboard listens on `127.0.0.1` only. Passkeys need a real hostname with valid TLS — a bare
+IP can never be a WebAuthn RP ID — so the supported path is Tailscale Serve:
+
+```sh
+tailscale serve --bg 127.0.0.1:8791
+tailscale serve status                      # read the https://<box>.<tailnet>.ts.net URL
+glance set-origin https://<box>.<tailnet>.ts.net
+glance enroll
+```
+
+Then open the printed URL on the phone, type the code, and create the passkey. The phone must be
+on the same tailnet.
+
+Changing the origin changes the RP ID, which invalidates existing passkeys. Say so before running
+`set-origin` on a working setup.
+
+## Remote approve/deny
+
+`glance approval risky` makes `Bash`, `Write`, `Edit`, `MultiEdit` and `NotebookEdit` calls pause
+and wait for a tap on the phone. Defaults that matter:
+
+- Nothing waits unless a phone is actually watching the dashboard (`requireWatcher`).
+- If nobody answers within 90s the call is **allowed**, not denied. Flip that on the phone's
+  settings panel if you want the opposite.
+- Every failure path is fail-open: daemon down, timeout, bad JSON — the tool call proceeds. This
+  is a convenience gate, not a security boundary.
+
+`glance approval off` (the default) means Grok Build never blocks on the phone.
+
+## When something does not work
+
+- **"not running"** → `glance up`, then `glance logs`.
+- **Passkey prompt fails with a security error** → the phone is on a hostname the RP ID does not
+  cover. Compare `glance status`'s `rp id` with the hostname in the phone's address bar.
+- **Dashboard loads but shows nothing** → hooks are not firing. Check that the port in
+  `hooks/hooks.json` matches `~/.grok/glance/config.json`; `glance sync-hooks` fixes it.
+- **Page says "run npm install && npm run build"** → the web bundle is missing; build it.
+
+## What it deliberately does not do
+
+Read-only plus approve/deny. It cannot send prompts, edit files, run tools, or resume a session.
+Do not tell the user otherwise.