Chat is a narrow channel: a column of text, with no real way to lay out a comparison, drag a list into order, mark up an image, or hand back a dense table you can act on row by row. surface
is your agent's escape hatch — it builds a web page shaped to the task at hand, hands you a link, and reacts to whatever you do on it. The page can be as plain as a single approval button or as rich as a drag-to-rank board, an annotated floor plan, or a refereed two-player game; either way it's built for one task and thrown away when that task is done — no app to stand up, no form to maintain.
More precisely: surface
is a pattern + skill for an agent to generate an ephemeral, structured UI at a URL, deliver that URL through any channel it has, and drain submissions autonomously — reacting on its own, without you coming back to chat to say "I clicked it." The agent decides what every control on the page means, so submissions arrive in a known shape. It's also a strong way to show you information — tables, grouped lists, flagged rows — that a wall of chat text can't.
You don't run surface; you install the skill, then ask your agent. In Claude Code (CLI or Desktop):
/plugin marketplace add aac/surface
/plugin install surface@surface
(On Codex, or to install by hand, see Installing below.) Then ask your agent to build the canonical demo:
Use the surface skill to build me a tic-tac-toe game I can play in my browser:
I'll click squares to play X, and you drain each of my moves off the wire and
play O back onto the same board, until someone wins.
Soon you have a browser tab with a real board: your clicks land as X, and O appears a second or two later — played by your agent, drawn onto the same surface. (The first build takes a little longer — the agent is writing the server — but once it's up, your moves come back live.) That one prompt exercises the whole pattern.
Prerequisites: none beyond the skill. For a local browser demo the agent writes and runs whatever small server it needs — you don't pre-install Go, Node, or Python (the reference servers in this repo are there to read, not to install). The local demo runs on loopback and needs no setup. One caveat: the tic-tac-toe board pulls its drawing library (tldraw) from a CDN, so that browser tab needs internet.
Same pattern, wildly different shapes — each is a single ask:
- "Show me these 8 thumbnails and let me click the one to ship."
- "Give me a drag-to-rank surface for these 10 priorities, then tell me the order I chose."
- "Render these 30 flagged transactions as a table with approve / reject per row, and act on my picks."
- "Build an approval gate for this deploy, text me the link, and proceed only once I approve."
The agent shapes the UI to the task and throws it away when the task is done.
A handful of terms recur — here's the whole vocabulary:
Surface— the throwaway page itself, living at a URL.** Affordance**— a control on the surface (a button, a cell, an upload field). Each carries an** opaque ID**the agent mints; the agent keeps a private map from ID → what that controlmeans, so a submission can't be twisted into meaning something it shouldn't.Drain— the agent consuming submissions as they arrive and reacting on its own. This is the non-negotiable part: a surface you have to return to chat to act on has failed the pattern.Substrate / the wire—howthe surface is served and submissions travel: a local HTTP server, a hosted Cloudflare Worker, a Slack message, raw sockets. The pattern is fixed; the substrate is a choice.The pattern— five invariants every implementation preserves: mint opaque IDs, persist the ID→intent map, render the surface, drain autonomously, stay ephemeral. It's the contract; everything else is illustration. Full statement inskills/surface/references/pattern.md
.
Agents already have three ways to collect structured input, each with a gap: a chat reply (unstructured, and only if the user is in chat), an inline chat-client widget (structured, but trapped inside a supported chat surface), or a purpose-built app or form (full UI, but real build-and-maintain cost). surface fills the space between them — task-shaped UI the agent generates for the moment and discards.
The honest objection is "isn't this just a web form?" The answer is no, and the reason is the shift in who builds it and how disposable it is:
The cost of bespoke collapsed to the cost of asking. A form builder gives you fixed fields and one respondent. surface lets an agent generate a UIshaped to the task— a drag-to-rank, a floor-plan annotator, a refereed two-player game, a flagged-transactions review with per-row decisions — in the time it takes to describe it, then throw it away. When making a custom interactive surface gets that cheap, the calculus flips: interactions that were never worth building a UI for (too one-off, too oddly-shaped, too ephemeral) become worth a surface, because nobody has to build and own anything.The URL carries the whole interaction. Because the response surface lives at the URL,anyoutbound channel — email, SMS, push, a paging system — becomes a reply path, not just a notification. That reframes "the user isn't in chat" from a dead end into a delivery choice.Reactions are code, so monitoring is cheap. The agent encodes the drain-and-react logic and lets it run; it only re-engages for submissions that genuinely need judgment. Watching a live surface is not an LLM-call-per-interaction tax — the mechanical reactions cost nothing once written.Ephemeral by default. Today surface aims at the moment, not forever: it fills the gapbelowthe threshold where standing up and maintaining a durable tool makes sense, and for durable, recurring needs a real app or form tool is still the right call.
The plugin (Quick start above) is the easiest path. The full picture:
Claude Code (CLI or Desktop):/plugin marketplace add aac/surface
, then/plugin install surface@surface
. The skill auto-loads fromskills/surface/
.Cowork / Claude Desktop: Customize → plugins → Add marketplace, and point it ataac/surface
.Codex: clone the repo and symlink the skill —ln -s "$PWD/skills/surface" ~/.codex/skills/surface
— or point your agent at this repo and let it install. (A first-class Codex plugin-marketplace path is on the way once the CLI's plugin flow settles.)Or just point your agent at this repo(github.com/aac/surface
) and let it install whatever way fits — the skill bundle is harness-neutral underskills/surface/
, and there's aninstall.sh
that symlinks it for you.
Each harness loads skills/surface/SKILL.md
and the references and examples it points to.
The first time you use surface interactively, the agent runs a quick setup pass: it surveys what your environment can do — local loopback, any tunnel CLIs, any hosted substrate you've configured — and records the findings, plus where the credentials for non-local delivery live (the locations, not the secrets), to ~/.surface/environment.md
. This is a discovery step the skill defines (SKILL.md
§7), not a command you run. Later sessions read that file instead of re-probing, and an agent running autonomously (cron, a scheduled job) reads it instead of asking you.
For a local browser demo you need none of this — loopback works out of the box, so "ask the agent for a tic-tac-toe game" just works. Setup earns its keep the moment you want surface to deliver a URL through another channel (email, SMS, a hosted endpoint): that's what the environment file is for.
surface deliberately ships narrow and grows on real-use signal. Currently out of scope:
A bundled/installable server binary. v0 is skill-only — the reference servers inskills/surface/examples/
exist to be read and re-implemented, not installed. A canonicalsurface-serve
is a v1 question.Templating / surface-authoring helpers. The agent writes the HTML/JS directly; a helper layer waits on friction signal.Substantive prompt-injection mitigation patterns.references/security.md
names the caution; deeper sanitization guidance accrues as real untrusted-input use does.Persistent surfaces, link expiration, one-time-use semantics. Surfaces are ephemeral; agents handle lifetime in their own state if they need it.
(Hosted deployment and a push/WebSocket transport were once on this list — both are now documented as reference substrates, in references/hosted-example.md
and references/websocket-example.md
. These ship as contracts to build against, not runnable servers: unlike the local wire's committed examples/server.go
, the hosted and WebSocket substrates have no reference implementation in the tree — the agent builds one for its environment from the reference. See "What's in this repo" below.)
surface depends on nothing else and knows about no other tool — but two sibling tools compose with it naturally, and an agent that has them gets more leverage:
— an agent-to-human request inbox. A surface is a good way toask
presentthe thing an ask is about (a decision laid out as a board, a batch to review), while the ask itself is the durable record that a human action is pending. Surfaces are ephemeral; an ask survives the session.— delivers a payload through whatever channel a recipient prefers (SMS, email, push). When a surface's URL needs to travel to someone who isn't in chat, reach is the natural way to send it.reach
Neither is required; surface works standalone. The composition lives in the agent's hands, not in surface's code.
Shipped as the skill (loaded at runtime, all under skills/surface/
):
| Path | Purpose |
|---|---|
skills/surface/SKILL.md |
|
| Skill entry point — what surface is, when to use it, links into the references. | |
skills/surface/references/pattern.md |
|
| The substrate-agnostic pattern. The contract every implementation must preserve. | |
skills/surface/references/wire-example.md |
|
| One concrete wire (HTTP + JSON over localhost). Illustrative, not normative. | |
skills/surface/references/lifecycle.md |
|
| The mechanism space for autonomous draining (Monitor, polling, fs watch, push webhook). | |
skills/surface/references/security.md |
|
| Trust boundary, deployment posture, free-field content as injection vector. CSRF + URL-unguessability notes for non-loopback deployments. | |
skills/surface/references/hosted-example.md |
|
Cloudflare Worker + KV wire walkthrough — sibling to wire-example.md , for the hosted substrate. |
|
skills/surface/examples/server.go |
|
Go reference server implementing the wire example. Supports either stdout (SUBMIT lines) or filesystem-drop drain via --drain-mode={stdout,fs} . Read it for orientation, re-implement in whatever fits. |
|
skills/surface/examples/server_test.go |
|
| Tests for the Go reference. | |
skills/surface/examples/server.py |
|
| Python stdlib reference, independently derived from the references (not Go-mirrored). Diverges from the Go sibling on operational details (port 8000, no parent-death watchdog, hard 32 MiB multipart cap) — same wire contract. | |
skills/surface/examples/server.mjs , server.test.mjs |
|
Node stdlib reference (node:http ), independently derived from the references; node:test suite (21 cases). |
|
skills/surface/examples/rust/ |
|
Rust reference server (zero-dependency std::net ), independently derived from the references. Cargo project — cargo run / cargo test . |
|
skills/surface/examples/tic-tac-toe.html , tic-tac-toe.md |
|
The showcase demo — a tldraw tic-tac-toe surface (you play, the agent drains moves and replies on the board), with the .md explaining how it maps onto the pattern and how to drive it by hand. |
The Python, Node, and Rust references were each built without their author reading the other siblings — derived from skills/surface/references/
alone. The operational divergences (different ports, watchdog choices, error-status policies) are the validation: the pattern survives independent re-derivation.
Packaging (harness-specific plugin wrappers, not loaded as part of the skill):
| Path | Purpose |
|---|---|
.claude-plugin/plugin.json |
|
Claude plugin manifest. Makes the bundle installable as a Claude Desktop / Cowork plugin; skills under skills/ are auto-discovered. |
|
.codex-plugin/plugin.json |
|
Codex plugin manifest. Sibling to the Claude manifest with the same skills/ pointer and lockstep version . Harness-neutral skill content stays under skills/surface/ . |
For humans (not loaded by the skill):
| Path | Purpose |
|---|---|
README.md |
|
| This file. | |
LICENSE |
|
| Apache 2.0. | |
AGENTS.md |
|
Conventions for agents and contributors working on surface itself (load-bearing design principles, branch policy, halt conditions). CLAUDE.md is a thin shim that imports it so Claude Code auto-loads it. |
|
skills/surface/go.mod |
|
| Go module declaration for the reference server. |
The drain mechanism (how the agent learns of submissions) is harness-neutral as a category, but maps to different primitives:
| Category | Claude Code | Codex |
|---|---|---|
| Push-stream on subprocess stdout | Bash(run_in_background) + Monitor |
|
Long-running exec_command session + write_stdin /output polling |
||
| Scheduled wake-ups for cadence | ScheduleWakeup , /loop |
|
| Heartbeat automations | ||
| FS drop-directory watch | fswatch /inotifywait /polling |
|
| Same — OS-level primitives are harness-neutral | ||
| Hosted poll | WebFetch / HTTP |
|
WebFetch / HTTP — same |
||
| Tear-down | KillShell |
|
| Codex session/process-group teardown |
A surface that requires the user to come back to chat and say "I clicked it" has failed the pattern. Any adaptation must include a real drain path (long-running stdout polling, drop-directory polling, heartbeat-driven re-check, hosted poll, or webhook where available).
+skills/surface/SKILL.md
— the canonical design: the pattern, the wire example, lifecycle mechanisms, security stance. Start here to understand the shape of the thing.references/
— the load-bearing principles (trust the agent, pattern is the contract, autonomous draining is foundational). Read before changing anything in the skill bundle. (AGENTS.md
CLAUDE.md
just imports this for Claude Code.)
This skill has no phone-home. It emits no telemetry and collects no data. Any outbound network activity happens only through hosted-substrate references the user explicitly opts into (e.g., the Cloudflare Worker reference), and is entirely controlled by the operator.
Licensed under the Apache License, Version 2.0. See LICENSE for details.