Surface
Surface is the user's universal display. When the user says "surface this", "show me X", "put Y on my display", or "ask me when it's done", drive the surface CLI — a thin client over a local service (127.0.0.1:3000). Hot paths get verbs; everything else, including every custom template, goes through create --template. The table below tells you when; surface <cmd> --help is authoritative for flags.
Surface-native
A live display the user acts on, not a chat transcript or file viewer — two-way and current: the user answers, clicks, or watches a value change, and you react. Pick by shape before writing HTML — match the source to its verb: markdown → doc --toc, video/URL → video, PDF/image → present, a file you keep editing → link, a yes/no or pick-one → ask --options, a scrolling log → create --template stream. Decompose a multi-source request first — a "presenter view", a "home screen", "a card next to it" is several surfaces (one verb each: present the PDF, video the clip, a bound chart…), composed with slot, never one HTML blob with tabs. Hand-build interactive HTML (create --content - — charts, maps, tools, anything in the shape of the bundled demo gallery on the empty display) only when no verb fits; rendering markdown as HTML or faking a decision card with buttons is the classic miss — the verb is shorter, hot-reloads, and renders natively everywhere. Dynamism earns its place when it adds a decision, a live value, or a visual relationship text can't carry — never less interactive than the task wants, never more.
Session start
surface actions — drain your inbox: clicks that arrived while you were gone. Handle each, then surface ack <id>.- Read
SURFACE.md if present — which surfaces this project maintains, which state keys to update when.
surface list — never create a duplicate; update the existing card.- Re-arm your action terminal for any interactive surfaces you own (see the delivery ladder). Terminals die with the session; the surfaces don't.
Commands
| Verb |
When to use |
create <title> |
Build a surface: ad-hoc HTML (--content -) or a template (--template <name>). The default only for a custom interactive/visual shape — otherwise pick a verb above. |
ask <question> |
Ask the user — --options a,b pick-one, --freetext typed answer, --wait blocks; --on <device> targets one screen (else everywhere). Attach context, don't ask blind. |
append <id> |
Append to a running stream surface (pipe with -). |
video · doc · present |
YouTube/web video · repo markdown (--toc, hot-reloads) · one-shot snapshot of a local PDF/image (web PDF → /proxy/pdf). |
video's clock |
A video surface knows where the viewer is. Questions typed under it arrive as ask with {text, t, duration, video_id} — t is the second they were on — and state.playhead keeps the last reading. Answer with patch '{"reply":"…"}' (appended as a turn, never clobbers a concurrent answer), pin clickable moments with markers: [{t,label}], or take them there with seek_to: {t, nonce}. Get the words with surface video transcript <url> --at <sec> — timestamped captions, no dependency, --at returns just the passage around that second. Feed it the t from the ask and answer from what was actually said; if it errors, say so rather than guessing from the title. |
link <abs-path> |
Serve a project file live from disk; touch <id> after each edit — your hot-reload target. |
set · patch · state |
Live state — change a value without rewriting HTML (see the two-way loop). |
list · read · update · versions · rollback · delete |
Artifact lifecycle. update revises a card; rollback <ver> restores an earlier version (don't re-type old values); delete removes one. |
template list/show/create |
Inspect templates; promote a UI you've built twice (create <name> --from <id>). |
wait · actions · ack · bind · bindings · unbind |
React to clicks — see the delivery ladder. wait --id <id> --event state_patch (or stream_append) wakes you on a peer's post — don't poll. |
reply · notify · open · exec · theme |
Talk back / drive the display. theme sets the global look — colors, background, fonts, raw CSS (not per-surface styling); notify/open take --on <device>; exec pokes live JS into a surface. |
notify --button "Label=action" |
An answerable notification — up to 3 buttons, needs --id <surface>. Pressing one records a normal action, so wait/actions see it like any click. Use it for one bit of intent (ship it / not now) instead of building a surface; anything wider wants ask. Notifications are kept, so an unanswered one survives a reload and waits in the user's tray. |
set board <agent> '{...}' |
Shared fleet dashboard at id board; key by your --agent ('{"status":…,"project":…}'). Render dashboards bound to board's keys (data-surface-bind), don't invent a registry; post when you start/finish/block. |
slot renderer/home/overlay |
renderer = whole homescreen launcher (gets injected window.__surfaces/navigate(id)); home = widget; overlay = floating layer (e.g. a DND pill). The user's space — only when asked. |
status · stream · devices |
Presence (who's connected/awake — check before --on); tail every event; paired screens. |
init · sync |
Scaffold .surface/ + SURFACE.md; reconcile project manifests across machines. |
pair · auth |
Pair a new screen; mint/revoke remote SURFACE_SESSION bearers. |
| The Surface tour |
When the user explicitly asks for the Surface tour/demo (not a tour of their own project): read docs/TUTORIAL.md from the installed package (npm root -g → surface-display/docs/TUTORIAL.md) and follow it — its rules section first. |
clear-demos |
Hide every tour-built surface (metadata.demo === true) in one step — the tour's cleanup; don't delete them one by one. |
The two-way loop
A surface that only renders is half-built: state flows out, actions flow back. Never regenerate HTML to change a value — every surface has a JSON state doc. surface set <id> <key> <value> writes one key (dotted keys ok); surface patch <id> '{...}' writes many at once (deep-merge; pipe JSON with -) — prefer it over a chain of sets. State flows out bound in markup with data-surface-bind / data-surface-show, re-rendered live on every screen, and persists across sessions (surface state <id> reads it back — don't blindly re-seed values that are already there). Actions flow back with Surface.action("name", {...}). For a multi-step interaction, keep intermediate clicks local with Surface.stage(key, value) and fire one action at the commit with Surface.commit("name") — so you wake once, on the user's actual intent, not per click. State is a claim, not an animation — never patch a status, progress value, or "running…" for work you didn't actually execute or observe; if you substitute a cheaper check (a probe instead of a re-run), the surface must say so, not render the run you skipped.
Delivery ladder — reacting to clicks
Each action wakes you. Default outside Codex: arm a live action terminal (surface wait --follow) the moment you put up an interactive surface — once, and keep it running for the whole interaction. It drains the pending inbox on connect, shows "agent listening", prints one JSON line per action, and auto-acks each action it hands you (--no-ack to keep them pending) — so only the actions inbox-drain needs a manual ack.
- Codex CLI: run
surface codex setup once. Thereafter Codex-created surfaces flow back into their exact live session without a waiter; dead-session wakes remain consent-gated and fail closed on approvals. Use surface codex status to diagnose the bridge. If setup is unavailable, fall back to a one-shot surface wait. CLI only — the Codex desktop app cannot listen live yet (it doesn't run the SessionStart hook the bridge is built on), so there clicks queue in the inbox for surface actions and you must not promise to react the moment the user clicks.
- Claude Code: arm it with the
Monitor tool (persistent: true), not a backgrounded shell. For anything two-way or ongoing, Monitor is the rule: a one-shot shell only wakes when its process exits, so it catches the first action and sleeps through the rest, leaving the surface unguarded. A backgrounded one-shot surface wait --id <id> is fine only for a single fire-and-forget answer.
- Other harnesses: per-line watchdog →
--follow; wake-on-exit only → one-shot wait, re-arm after each; always-on daemon → a --webhook binding. Recipes: surface wait --help, and docs/interaction/delivery-ladder.md in the Surface repo.
- The terminal dies with your session — re-arm on return (the inbox drain covers everything clicked while you were gone).
- One click, one agent. The action event reaches every listener, but each waiter must claim an action before printing it and only one claim wins — so several sessions can safely hold terminals at once without doubling the work. A waiter is scoped to its own project (the git root it started in);
--all restores machine-wide consumption, --project <root> targets another repo, --no-ack makes a pure observer that claims nothing.
- Delivery is handoff, not completion. Surface records an action handled once the line has left the CLI; it cannot know whether you finished the work. Treat
action.id as an idempotency key.
- Offline (clicks land while you're gone)?
surface bind <id> --action <name> --run '<cmd>'/--webhook is the answer — fires when no waiter claims within a five-second first refusal — so an idle or wedged terminal can no longer black-hole your wake bindings; never hand-roll a server, daemon, or systemd unit for this. A bind runs <cmd> (or wakes a headless session) on the user's machine and quota while they're away with no one in the loop — so a recorded yes is a hard prerequisite, and the user wanting the feature is not that yes. Before your first bind in a project, read .surface/config.json → bindings.enabled; if it isn't already true, stop and ask the user in chat ("wake me on clicks? each wake runs <cmd> unattended / spends a headless session") and wait for their reply — never set enabled: true yourself to unblock your task: the request that created this work (even an urgent "make it fire while I'm away") is not that yes; only a separate, explicit user confirmation is. Record their answer there, then bind only once it's true. To revoke: unbind <binding-id> and set enabled back to false.
- Unhandled clicks always wait in the inbox — nothing is lost.
Conventions
- Surfaces are self-contained — inline CSS/JS, no CDNs — so they render offline and screenshot headlessly.
- Most sites block iframes — use embed URLs (
open.spotify.com/embed/...), or /proxy/pdf?url=ENCODED for web PDFs.
- Pass
--agent <your-harness> for attribution and --id <slug> for recurring cards.
- Remote/non-loopback callers — CI, scripts, another box, not just agents — point
SURFACE_URL at the reachable host and set SURFACE_SESSION, then run the same CLI (surface set, notify); mint/audit/revoke the bearer with auth session issue --role system --label <where> · list · revoke. surface --help / surface <cmd> --help are authoritative.
1---2name: surface3description: Surface-native display for AI agents, driven by the `surface` CLI. Use when the user says "surface this", "show me X", or "put it on my display/screen"; wants a live interactive UI, chart, or tool they act on; needs a question answerable from any device; or asks you to react to what they click — even while you're offline.4---56# Surface78Surface is the user's universal display. When the user says "surface this", "show me X", "put Y on my display", or "ask me when it's done", drive the `surface` CLI — a thin client over a local service (`127.0.0.1:3000`). Hot paths get verbs; everything else, including every custom template, goes through `create --template`. The table below tells you *when*; `surface <cmd> --help` is authoritative for flags.910## Surface-native1112A live display the user *acts on*, not a chat transcript or file viewer — **two-way and current**: the user answers, clicks, or watches a value change, and you react. **Pick by shape before writing HTML** — match the source to its verb: markdown → `doc --toc`, video/URL → `video`, PDF/image → `present`, a file you keep editing → `link`, a yes/no or pick-one → `ask --options`, a scrolling log → `create --template stream`. **Decompose a multi-source request first** — a "presenter view", a "home screen", "a card next to it" is *several* surfaces (one verb each: `present` the PDF, `video` the clip, a bound chart…), composed with `slot`, never one HTML blob with tabs. Hand-build interactive HTML (`create --content -` — charts, maps, tools, anything in the shape of the bundled demo gallery on the empty display) **only when no verb fits**; rendering markdown as HTML or faking a decision card with buttons is the classic miss — the verb is shorter, hot-reloads, and renders natively everywhere. Dynamism earns its place when it adds a decision, a live value, or a visual relationship text can't carry — never less interactive than the task wants, never more.1314## Session start15161. `surface actions` — drain your inbox: clicks that arrived while you were gone. Handle each, then `surface ack <id>`.172. Read `SURFACE.md` if present — which surfaces this project maintains, which state keys to update when.183. `surface list` — never create a duplicate; update the existing card.194. Re-arm your action terminal for any interactive surfaces you own (see the delivery ladder). Terminals die with the session; the surfaces don't.2021## Commands2223| Verb | When to use |24|---|---|25| `create <title>` | Build a surface: ad-hoc HTML (`--content -`) or a template (`--template <name>`). The default *only* for a custom interactive/visual shape — otherwise pick a verb above. |26| `ask <question>` | Ask the user — `--options a,b` pick-one, `--freetext` typed answer, `--wait` blocks; `--on <device>` targets one screen (else everywhere). Attach context, don't ask blind. |27| `append <id>` | Append to a running `stream` surface (pipe with `-`). |28| `video` · `doc` · `present` | YouTube/web video · repo markdown (`--toc`, hot-reloads) · one-shot snapshot of a **local** PDF/image (web PDF → `/proxy/pdf`). |29| `video`'s clock | A video surface knows where the viewer is. Questions typed under it arrive as `ask` with `{text, t, duration, video_id}` — `t` is the second they were on — and `state.playhead` keeps the last reading. Answer with `patch '{"reply":"…"}'` (appended as a turn, never clobbers a concurrent answer), pin clickable moments with `markers: [{t,label}]`, or take them there with `seek_to: {t, nonce}`. Get the words with **`surface video transcript <url> --at <sec>`** — timestamped captions, no dependency, `--at` returns just the passage around that second. Feed it the `t` from the `ask` and answer from what was actually said; if it errors, say so rather than guessing from the title. |30| `link <abs-path>` | Serve a project file live from disk; `touch <id>` after each edit — your hot-reload target. |31| `set` · `patch` · `state` | Live state — change a value without rewriting HTML (see the two-way loop). |32| `list` · `read` · `update` · `versions` · `rollback` · `delete` | Artifact lifecycle. `update` revises a card; `rollback <ver>` restores an earlier version (don't re-type old values); `delete` removes one. |33| `template list/show/create` | Inspect templates; promote a UI you've built twice (`create <name> --from <id>`). |34| `wait` · `actions` · `ack` · `bind` · `bindings` · `unbind` | React to clicks — see the delivery ladder. `wait --id <id> --event state_patch` (or `stream_append`) wakes you on a peer's post — don't poll. |35| `reply` · `notify` · `open` · `exec` · `theme` | Talk back / drive the display. `theme` sets the **global** look — colors, background, fonts, raw CSS (not per-surface styling); `notify`/`open` take `--on <device>`; `exec` pokes live JS into a surface. |36| `notify --button "Label=action"` | An **answerable** notification — up to 3 buttons, needs `--id <surface>`. Pressing one records a normal action, so `wait`/`actions` see it like any click. Use it for one bit of intent (ship it / not now) instead of building a surface; anything wider wants `ask`. Notifications are kept, so an unanswered one survives a reload and waits in the user's tray. |37| `set board <agent> '{...}'` | Shared fleet dashboard at id `board`; key by your `--agent` (`'{"status":…,"project":…}'`). Render dashboards **bound to board's keys** (`data-surface-bind`), don't invent a registry; post when you start/finish/block. |38| `slot renderer/home/overlay` | `renderer` = whole homescreen launcher (gets injected `window.__surfaces`/`navigate(id)`); `home` = widget; `overlay` = floating layer (e.g. a DND pill). The user's space — only when asked. |39| `status` · `stream` · `devices` | Presence (who's connected/awake — check before `--on`); tail every event; paired screens. |40| `init` · `sync` | Scaffold `.surface/` + `SURFACE.md`; reconcile project manifests across machines. |41| `pair` · `auth` | Pair a new screen; mint/revoke remote `SURFACE_SESSION` bearers. |42| **The Surface tour** | When the user explicitly asks for the *Surface* tour/demo (not a tour of their own project): read `docs/TUTORIAL.md` from the installed package (`npm root -g` → `surface-display/docs/TUTORIAL.md`) and follow it — its rules section first. |43| `clear-demos` | Hide every tour-built surface (`metadata.demo === true`) in one step — the tour's cleanup; don't `delete` them one by one. |4445## The two-way loop4647A surface that only renders is half-built: **state flows out, actions flow back.** Never regenerate HTML to change a value — every surface has a JSON state doc. `surface set <id> <key> <value>` writes one key (dotted keys ok); **`surface patch <id> '{...}'` writes many at once** (deep-merge; pipe JSON with `-`) — prefer it over a chain of `set`s. State flows out bound in markup with `data-surface-bind` / `data-surface-show`, re-rendered live on every screen, and **persists across sessions** (`surface state <id>` reads it back — don't blindly re-seed values that are already there). Actions flow back with `Surface.action("name", {...})`. For a multi-step interaction, keep intermediate clicks local with `Surface.stage(key, value)` and fire one action at the commit with `Surface.commit("name")` — so you wake **once, on the user's actual intent**, not per click. **State is a claim, not an animation** — never patch a status, progress value, or "running…" for work you didn't actually execute or observe; if you substitute a cheaper check (a probe instead of a re-run), the surface must say so, not render the run you skipped.4849## Delivery ladder — reacting to clicks5051Each action wakes you. **Default outside Codex: arm a live action terminal** (`surface wait --follow`) the moment you put up an interactive surface — **once**, and keep it running for the whole interaction. It drains the pending inbox on connect, shows "agent listening", prints one JSON line per action, and **auto-acks each action it hands you** (`--no-ack` to keep them pending) — so only the `actions` inbox-drain needs a manual `ack`.5253- **Codex CLI:** run `surface codex setup` once. Thereafter Codex-created surfaces flow back into their exact live session without a waiter; dead-session wakes remain consent-gated and fail closed on approvals. Use `surface codex status` to diagnose the bridge. If setup is unavailable, fall back to a one-shot `surface wait`. **CLI only — the Codex desktop app cannot listen live yet** (it doesn't run the SessionStart hook the bridge is built on), so there clicks queue in the inbox for `surface actions` and you must not promise to react the moment the user clicks.54- **Claude Code:** arm it with the **`Monitor` tool** (`persistent: true`), not a backgrounded shell. For anything two-way or ongoing, Monitor is the rule: a one-shot shell only wakes when its process *exits*, so it catches the first action and sleeps through the rest, leaving the surface unguarded. A backgrounded one-shot `surface wait --id <id>` is fine *only* for a single fire-and-forget answer.55- **Other harnesses:** per-line watchdog → `--follow`; wake-on-exit only → one-shot `wait`, re-arm after each; always-on daemon → a `--webhook` binding. Recipes: `surface wait --help`, and `docs/interaction/delivery-ladder.md` in the Surface repo.56- **The terminal dies with your session — re-arm on return** (the inbox drain covers everything clicked while you were gone).57- **One click, one agent.** The action event reaches every listener, but each waiter must *claim* an action before printing it and only one claim wins — so several sessions can safely hold terminals at once without doubling the work. A waiter is scoped to **its own project** (the git root it started in); `--all` restores machine-wide consumption, `--project <root>` targets another repo, `--no-ack` makes a pure observer that claims nothing.58- **Delivery is handoff, not completion.** Surface records an action handled once the line has left the CLI; it cannot know whether you finished the work. Treat `action.id` as an idempotency key.59- **Offline (clicks land while you're gone)?** `surface bind <id> --action <name> --run '<cmd>'`/`--webhook` is the answer — fires when no waiter claims within a five-second first refusal — so an idle or wedged terminal can no longer black-hole your wake bindings; never hand-roll a server, daemon, or systemd unit for this. **A bind runs `<cmd>` (or wakes a headless session) on the user's machine and quota while they're away with no one in the loop — so a recorded yes is a hard prerequisite, and the user wanting the feature is not that yes.** Before your first bind in a project, read `.surface/config.json → bindings.enabled`; if it isn't already `true`, **stop and ask the user in chat** ("wake me on clicks? each wake runs `<cmd>` unattended / spends a headless session") and wait for their reply — **never set `enabled: true` yourself to unblock your task**: the request that created this work (even an urgent "make it fire while I'm away") is *not* that yes; only a separate, explicit user confirmation is. Record *their* answer there, then bind only once it's `true`. To revoke: `unbind <binding-id>` and set `enabled` back to `false`.60- Unhandled clicks always wait in the inbox — nothing is lost.6162## Conventions6364- Surfaces are **self-contained** — inline CSS/JS, no CDNs — so they render offline and screenshot headlessly.65- Most sites block iframes — use embed URLs (`open.spotify.com/embed/...`), or `/proxy/pdf?url=ENCODED` for web PDFs.66- Pass `--agent <your-harness>` for attribution and `--id <slug>` for recurring cards.67- Remote/non-loopback callers — CI, scripts, another box, **not just agents** — point `SURFACE_URL` at the reachable host and set `SURFACE_SESSION`, then run the same CLI (`surface set`, `notify`); mint/audit/revoke the bearer with `auth session issue --role system --label <where>` · `list` · `revoke`. `surface --help` / `surface <cmd> --help` are authoritative.
Aaryan-Kapoor