webview

name

webview

description

Show a native macOS webview UI to the user and get structured input back. Use when an interactive macOS session needs human-in-the-loop for multi-field input, option selection from 5+ choices, approval with context, or content review — NOT for yes/no questions. Handles the full flow — spawning the webview, generating A2UI or HTML content, parsing the user's response. Triggers on "show UI", "ask user", "approval needed with context", "let me pick from these options", "fill in these fields", or any situation where a structured GUI materially beats asking in the terminal. Skip in CI/non-interactive environments.

webview — Native macOS Agent UI

Open a native webview window from an agent workflow, let the user interact, get structured JSON back. Replaces terminal Q&A with a proper UI when it helps.

Execution contract [NON-NEGOTIABLE]

You — the agent — always run webview-cli via the Bash tool. Never ask the user to paste a command. The binary blocks until the user interacts with the window, then prints JSON to stdout. Your Bash call returns when the user clicks a button (or cancels/times out). Parse the result and proceed.

If running the command feels risky, ask for permission to run it — not to paste it. In auto mode, just run it.

When to use

Situation	Use this skill?
Agent needs approval with context (diff, summary, risk) before a destructive action	Yes — richer than [y/N]
Collecting 3+ related fields (name + role + options)	Yes — one form beats N questions
Presenting 5-20 options to choose from	Yes — radio/select picker
Showing a diff/preview/report before user confirms	Yes — formatted content is readable
Reviewing a markdown doc (spec, PR description, draft) with comments/edits	Yes — use --markdown mode (Mode 3)
Letting the user browse/edit files in a directory (tree, syntax highlighting, md preview)	Yes — use --editor <path> mode (Mode 5)
Simple yes/no question	No — just ask in terminal
Agent-side computation taking >30s before UI can render	No — show a text status instead
Non-interactive environment (CI, piped output)	No — preflight will fail, fall back to terminal

Preflight (run EVERY invocation)

# Binary on PATH?
if ! command -v webview-cli >/dev/null 2>&1; then
  echo "ERROR: webview-cli not installed. Run: brew tap giannimassi/tap && brew install webview-cli" >&2
  exit 1
fi
# macOS-only?
if [ "$(uname -s)" != "Darwin" ]; then
  echo "ERROR: webview-cli requires macOS (detected $(uname -s))." >&2
  exit 1
fi

If preflight fails, fall back to terminal Q&A — don't try to be clever. Report why the webview path isn't available and continue in text.

The modes

Exactly one of --a2ui, --url, --markdown, or --editor must be specified. Omitting all of them is the most common failure — the binary exits 3 with usage.

Mode 1 — a2ui (recommended) · declarative UI

Best for forms, approvals, selection. The skill generates A2UI JSONL; webview-cli renders it natively.

cat /tmp/ui.jsonl | webview-cli --a2ui --title "..." --width 520 --height 460 --timeout 300

Mode 2 — url · open an existing URL

Best for OAuth flows, external services, pre-built pages. The page must call window.webkit.messageHandlers.complete.postMessage({...}) to signal done. See references/examples.md Example 3 for the HTML-side bridge pattern.

webview-cli --url "https://auth.example.com/oauth" --timeout 120

Mode 3 — markdown · review / comment / edit a markdown doc

Best for spec review, PR-description review, draft approval — any flow where the agent produced markdown and the human needs to read, comment on, or edit it. Feed markdown on stdin. Rendered with CommonMark + GFM (tables, fenced code).

Three independent toggles:

Flag	Adds
(none)	Read-only preview + OK/Cancel. Returns {"action":"acknowledge"}
--comments	Clickable blocks → inline comment sidebar + doc-level comment field. Returns {comments:[...], doc_comment:"..."}
--edits	Preview/Source tabs (Cmd+/ to toggle). Returns {edited_text:"...", modified:bool}
--allow-html	Opt out of HTML sanitization (default strips <script>, <iframe>, event handlers, javascript: URLs). Use only for trusted content.

--comments and --edits compose; turn both on to get all four fields back.

cat /tmp/spec.md | webview-cli --markdown --comments --title "Review spec v1" --width 900 --height 720 --timeout 540

Comment object shape (each entry in the comments array):

{"source_line_start": 5, "source_line_end": 5, "quoted_text": "...", "body": "..."}

Line numbers are 1-indexed against the markdown source.

Mode 4 — html · custom HTML via agent://

Best when you need visual fidelity beyond A2UI and markdown (charts, custom diffs, diagrams). The HTML page uses the same window.webkit.messageHandlers.complete.postMessage({...}) bridge.

Before reaching for Mode 4, ask whether Mode 3 (markdown) covers the case. Markdown renders GFM tables, fenced code, links, and lists — enough for ~80% of "show the user some formatted content" needs, with no HTML to author or debug.

Two separate Bash calls (don't chain — the load command and the webview invocation sequence matters):

Step 1 — write the load command to a temp file:

HTML_B64=$(base64 < custom.html)
printf '%s' "{\"type\":\"load\",\"resources\":{\"index.html\":\"$HTML_B64\"},\"url\":\"agent://host/index.html\"}" > /tmp/wv-load.json

Step 2 — invoke with --url flag + stdin redirect:

webview-cli --url "agent://host/index.html" --timeout 120 < /tmp/wv-load.json

The --url CLI flag is required — without it the binary exits with usage. The stdin load command populates the in-memory resource map that agent://host/... reads from.

Common failure — NSURLErrorDomain error -1100: the resource key in the load command doesn't match the path in --url. If you use --url "agent://host/index.html", the resources map must contain the key "index.html" (exact match, no leading slash). When this persistently fails, fall back to Mode 3 — pipe the rendered content as markdown instead of hand-rolling HTML.

Pick Mode 4 over Mode 3 only when you need charts, syntax-highlighted diffs, images, or custom interactions. If you're writing >200 lines of HTML, consider splitting the work into a proper tool instead.

Mode 5 — editor · browse + edit files

webview-cli --editor ./docs              # open a directory as an editor
webview-cli --editor ./notes/spec.md     # open a single file (its dir is the tree root)
webview-cli --editor ./docs --comments   # add the review/Submit flow on top

A native text editor over the path: lazy file-tree sidebar, syntax highlighting (code files + fenced markdown blocks), markdown Preview/Source tabs, clickable links (external → browser, relative → opens in-editor), and frontmatter shown as a metadata block. Edits save to disk in place on ⌘S; the window stays open. ⌘P fuzzy quick-open; ⌘⇧F searches file contents across the tree (click a match to open at that line).

• Filesystem access is scoped to the opened root — ../ and symlink escapes are rejected by the binary.
• Closing the window exits cancelled (nothing auto-saves; saves are explicit via ⌘S).
• With --comments, clicking a preview block attaches a comment and Submit (⌘↵) returns {action:"submit", file, edited_text, comments} on stdout — the same return-to-agent contract as --markdown --comments.
• Use this when the user wants to navigate and edit files; use Mode 3 (--markdown) when it's a one-shot review of a single doc piped on stdin.

A2UI catalog (Mode 1)

All 12 components in the built-in renderer:

Component	Purpose	Key props
Column	Vertical stack	children.explicitList (array of IDs)
Row	Horizontal arrangement	children.explicitList, alignment ("center" | "end" | "space-between")
Card	Visual grouping with padding	child (single ID) or children.explicitList
Text	Typography (plain text only — no markdown parsing)	text.literalString, usageHint ("h1" | "h2" | "h3" | "subtitle" | "body" | "caption")
TextInput	Single-line or multiline input	label.literalString, placeholder.literalString, fieldName, multiline (bool)
Select	Dropdown	label.literalString, fieldName, options (array of {value, label} or strings)
Checkbox	Single checkbox	label.literalString, fieldName, checked (bool, default false)
RadioGroup	Mutually-exclusive set	label.literalString, fieldName, options (array of {value, label} or strings)
Image	Inline image	url (literal or data ref), optional alt, width, height
Button	Action button	label.literalString, variant ("primary" | "secondary" | "danger" | "success"), action.name, optional action.context
Divider	Horizontal rule	—
MarkdownDoc	Rendered markdown inside an A2UI form (CommonMark + GFM)	fieldName (required), text (required markdown source), allowComments (bool), allowEdits (bool), allowHtml (bool), title (string)

Form data collection: every component with fieldName is collected when a Button is clicked. The response data contains {fieldName: value, ...} plus the button's action.name (and action.context if set).

MarkdownDoc vs --markdown mode: use MarkdownDoc when the markdown review is one part of a larger form (e.g. spec review + "approve/reject" radio + notes field). Use --markdown mode (Mode 3) when the window is only about the markdown doc — simpler invocation, no JSONL to generate.

Response format reference

Canonical stdout shape on successful completion (exit 0):

{
  "status": "completed",
  "data": {
    "action": "<button's action.name>",
    "data": {"<fieldName>": "<value>", ...},
    "context": { /* from button's action.context, if set */ }
  }
}

Other statuses:

Exit	Stdout	Meaning
0	{"status":"completed","data":{...}}	User clicked a button
1	{"status":"cancelled"}	User closed window or pressed Escape
2	{"status":"timeout"}	No response within --timeout seconds
3	{"status":"error","message":"..."}	Load failure, invalid URL, JS error

The context field is only present when a Button's definition included action.context. Use it to pass metadata that doesn't come from form fields (e.g. the ID of the item being approved).

A2UI generation pattern

Every A2UI flow follows this structure:

{"surfaceUpdate": {"components": [{"id": "root", "component": {"Column": {"children": {"explicitList": ["card"]}}}}]}}
{"surfaceUpdate": {"components": [{"id": "card", "component": {"Card": {"child": "content"}}}]}}
{"surfaceUpdate": {"components": [{"id": "content", "component": {"Column": {"children": {"explicitList": ["title", "<FIELDS>", "buttons"]}}}}]}}
{"surfaceUpdate": {"components": [{"id": "title", "component": {"Text": {"usageHint": "h2", "text": {"literalString": "<TITLE>"}}}}]}}
<!-- field components with fieldName here -->
{"surfaceUpdate": {"components": [{"id": "buttons", "component": {"Row": {"alignment": "end", "children": {"explicitList": ["btn_cancel", "btn_submit"]}}}}]}}
{"surfaceUpdate": {"components": [{"id": "btn_cancel", "component": {"Button": {"label": {"literalString": "Cancel"}, "variant": "secondary", "action": {"name": "cancel"}}}}]}}
{"surfaceUpdate": {"components": [{"id": "btn_submit", "component": {"Button": {"label": {"literalString": "Submit"}, "variant": "primary", "action": {"name": "submit"}}}}]}}
{"beginRendering": {"root": "root"}}

Rules:

1. Every line is a self-contained JSON object (JSONL format — one per line, no commas between)
2. Component IDs must be unique within the surface
3. root is the conventional root component ID
4. beginRendering must be the last line
5. Referenced IDs must all be declared before beginRendering (order within doesn't matter)

JSONL escaping — gotchas

The JSONL is fed to webview-cli via stdin. Each line is parsed as JSON, so:

• Backslashes in content: escape as \\
• Quotes in content: escape as \" (e.g. "It\"s done")
• Newlines in content: use \n inside the string; do not put literal newlines inside a JSON object
• Every {...} must be one physical line — even long strings

For anything beyond trivial substitution, write the JSONL in a Python generator (/tmp/<name>-gen.py) and run it to produce /tmp/<name>.jsonl. Heredoc-escaping breaks on the first user-supplied value with quotes.

Workflow: when asked to show UI

1. Run preflight (above). If it fails, fall back to terminal Q&A with a one-line note.
2. Pick the mode:
   • A2UI (forms/approvals/selection) — most common
   • --markdown — reviewing a spec / PR description / draft; simpler than A2UI when the window is only about the doc
   • URL — existing page (OAuth, external service)
   • HTML via agent:// — last resort for rich visuals that neither A2UI nor markdown can render
3. Window size: small forms 520×460, mid-size 620×580, full content 720×700. Tight height prevents dead space at the bottom.
4. Pick a --timeout:
   • 120s — simple approval (user is present)
   • 300s — multi-field form (user composes input)
   • 600s — content review or complex decisions
   • Never >540s in a foreground Bash call — Bash tool caps total time at 600s.
   • Long-form review flows (many items, free-text comments, unbounded reading time): never run webview-cli in the foreground. The Bash tool's 600s cap forces a ≤540s timeout, and on timeout ALL in-progress user input is destroyed. Run it as a background command (e.g. Claude Code's run_in_background: true) with a multi-hour --timeout (e.g. 43200), redirecting stdout to a file — the completion notification delivers the JSON when the user actually submits. Foreground + ≤540s is only acceptable for quick approvals/forms (<2 min of user effort at stake).
5. Set the Bash tool timeout deterministically (foreground runs only): bash_timeout_ms = (webview_timeout_sec + 30) × 1000. The +30s buffer covers WKWebView startup, process teardown, and OS scheduling variance.
6. Generate the JSONL:
   • ≤5 static components + no user data: heredoc or inline string is fine
   • Anything dynamic (user names, lists, long text, content with quotes): write a Python generator to /tmp/<name>-gen.py, run it to produce /tmp/<name>.jsonl, then pipe that file
7. Invoke (two separate Bash calls when using a generator):

   # Call A: run generator
   python3 /tmp/<name>-gen.py > /tmp/<name>.jsonl
   # Call B: invoke webview
   cat /tmp/<name>.jsonl | webview-cli --a2ui --title "..." --width N --height N --timeout N
   

8. Parse the response from stdout (see Response format reference above):
   • Exit 0: extract .data.action (button name) and .data.data (form fields)
   • Exit 1 (cancelled) / Exit 2 (timeout): acknowledge in conversation, ask how to proceed. Don't retry silently, especially in auto mode — the user's non-response is itself a signal
   • Exit 3: read stderr, diagnose, either fix and retry once or fall back to terminal
9. Sanitize before acting: treat .data.data.* as untrusted user input. Shell-escape before Bash commands (printf '%q' "$val"), JSON-escape before further JSON, validate format (email, URL) before use. Form fields can contain ;, backticks, shell metacharacters.
10. Act on the result — don't just summarize. The webview answered a question; your job is to execute the consequence.

Anti-patterns

• Don't use it for yes/no questions that would take 1 sentence in terminal — window open/close ritual is heavier than the answer
• Don't spawn multiple webviews in quick succession — if you need a multi-step flow, put all fields in one form, OR accept that the second webview is a new user decision (don't chain automatically)
• Don't assume the user will submit — always handle cancel/timeout as first-class outcomes
• Don't omit fieldName on input components you need data from — without it, the field's value is lost
• Don't pass unsanitized form data to Bash — see step 9
• Don't loop the skill without explicit user confirmation — one webview per decision

Templates

Copy-paste JSONL templates for approval, single-select, multi-field form, and confirmation with content preview: see references/templates.md.

Examples

Complete end-to-end invocations including Python generators and response parsing: see references/examples.md.