docs: add VHS demo gif and tighten README

Author: kanywst

README.md

@@ -13,40 +13,16 @@
 When you run multiple Claude Code sessions in parallel, every
 PreToolUse permission prompt fires in a different terminal.
 `approval-hub` aggregates them into a single TUI so you can resolve
-every request from one place — and the learned rules apply to future
-requests across all sessions.
+every request from one place. Learned rules apply to future requests
+across every session on the same machine.
 
-```text
-+- approval-hub ---------------------------------------------+
-| pending (2):                                               |
-|   > [a1b2c3d4] Bash: npm install               10:01:23    |
-|     [e5f6g7h8] Edit: .env.local                10:01:25    |
-|                                                            |
-+------------------------------------------------------------+
-| session_id: a1b2c3d4...                                    |
-| tool:       Bash                                           |
-| command:    npm install                                    |
-| cwd:        ~/proj/foo                                     |
-| matcher:    Bash(npm:*)                                    |
-|                                                            |
-| y once  n deny  a persist  d deny-persist  t ttl  ? help q |
-+------------------------------------------------------------+
-```
+<img src="assets/demo.gif" alt="approval-hub demo" width="900">
 
-## Highlights
-
-- **One TUI for every session.** Each session's PreToolUse hook posts
-  to a local broker; the broker pushes pending requests over SSE to a
-  single Bubble Tea TUI.
-- **Matcher learning.** `a` / `d` records a permission rule
-  (`Bash(npm test:*)`, `Edit(.env)`) so subsequent matching requests
-  resolve in about 30 ms without prompting.
-- **TTL rules.** `t` grants a one-hour pass instead of a forever rule.
-- **Fails safe.** Kill the broker and Claude Code's hook receives a
-  connection error; Claude Code falls back to its built-in prompt.
-  Nothing breaks.
-- **Local-only.** `127.0.0.1` listener, bearer token stored in `0600`
-  files, no network exposure.
+Two parallel Claude Code sessions queue PreToolUse requests; one TUI
+resolves them. `a` persists a learned `Bash(npm:*)` allow rule, `d`
+persists an `Edit(.env.local)` deny rule, and the next matching request
+from any session resolves from the store without prompting. `t` grants
+a TTL rule instead of a forever one.
 
 ## Install
 
@@ -135,8 +111,11 @@ the broker HTTP API.
 
 `approval-hub` listens on `127.0.0.1` only and authenticates every
 request with a `crypto/rand` 32-byte bearer token stored in `0600`
-files. See [SECURITY.md](SECURITY.md) for the threat model.
+files. If the broker is not running, Claude Code's hook gets a
+connection error and falls back to its built-in prompt, so no session
+is blocked by a daemon outage. See [SECURITY.md](SECURITY.md) for the
+threat model.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

assets/demo.gif

@@ -0,0 +1,66 @@
+Output assets/demo.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1180
+Set Height 640
+Set Padding 20
+Set TypingSpeed 35ms
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type `export TOKEN=$(jq -r .token "$HOME/Library/Application Support/approval-hub/config.json")`
+Enter
+Type "clear"
+Enter
+Show
+
+Type "# approval-hub: one TUI for every Claude Code permission prompt"
+Sleep 700ms
+Enter
+Sleep 600ms
+
+Type "# queue two PreToolUse requests from two parallel Claude sessions"
+Enter
+Sleep 400ms
+
+Type `curl -sS -X POST http://127.0.0.1:17456/decide -H "Authorization: Bearer $TOKEN" -d '{"session_id":"sess-web","cwd":"~/dev.to","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm install"}}' >/dev/null &`
+Enter
+Sleep 700ms
+
+Type `curl -sS -X POST http://127.0.0.1:17456/decide -H "Authorization: Bearer $TOKEN" -d '{"session_id":"sess-api","cwd":"~/api","hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":".env.local"}}' >/dev/null &`
+Enter
+Sleep 900ms
+
+Type "clear"
+Enter
+Sleep 300ms
+
+Type "approval-hub attach"
+Enter
+Sleep 2200ms
+
+Type "j"
+Sleep 600ms
+Type "k"
+Sleep 600ms
+
+Type "a"
+Sleep 1500ms
+
+Type "d"
+Sleep 1500ms
+
+Type "q"
+Sleep 600ms
+
+Type "clear"
+Enter
+Sleep 200ms
+
+Type "# learned rules persist across sessions"
+Enter
+Sleep 400ms
+Type "approval-hub list"
+Enter
+Sleep 2500ms