c11-browser

name	c11-browser
version	1
description	Browser automation for c11 browser surfaces (WKWebView-backed). Use to open sites, interact with pages, wait for state changes, extract data, save/load auth state, and validate UI changes without leaving c11. Prefer this over Chrome MCP whenever c11 is running.

c11 Browser Automation

Use this skill for browser tasks inside c11 webviews. Browser surfaces are a native surface type, scriptable alongside terminals and markdown viewers from the same c11 CLI. Prefer this over Chrome MCP whenever c11 is running: lighter, integrated, no stray Chrome windows.

Core Workflow

1. Open or target a browser surface.
2. Verify navigation with get url before waiting or snapshotting.
3. Snapshot (--interactive) to get fresh element refs.
4. Act with refs (click, fill, type, select, press).
5. Wait for state changes.
6. Re-snapshot after DOM/navigation changes.

c11 --json browser open https://example.com
# use returned surface ref, for example: surface:7

c11 browser surface:7 get url
c11 browser surface:7 wait --load-state complete --timeout-ms 15000
c11 browser surface:7 snapshot --interactive
c11 browser surface:7 fill e1 "hello"
c11 --json browser surface:7 click e2 --snapshot-after
c11 browser surface:7 snapshot --interactive

Surface Targeting

# identify current context
c11 identify --json

# open routed to a specific topology target
c11 browser open https://example.com --workspace workspace:2 --window window:1 --json

Notes:

• CLI output defaults to short refs (surface:N, pane:N, workspace:N, window:N).
• UUIDs are still accepted on input; only request UUID output when needed (--id-format uuids|both).
• Keep using one surface:N per task unless you intentionally switch.
• Default to a tab in the existing browser pane. If the workspace already has a browser pane, open new pages as tabs inside it rather than spawning a new browser pane — browsers are tabbed by default, and a fresh pane each time is the awkward interaction to avoid. Find the browser pane in c11 tree --json and add the tab with c11 new-surface --type browser --url <url> --pane <browser-pane-ref>. Open a new browser pane (c11 new-pane --type browser) only when none exists yet, or when the operator explicitly wants pages side by side. c11 browser open reuses an existing browser surface when one is available.

Wait Support

c11 supports wait patterns similar to agent-browser:

c11 browser <surface> wait --selector "#ready" --timeout-ms 10000
c11 browser <surface> wait --text "Success" --timeout-ms 10000
c11 browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
c11 browser <surface> wait --load-state complete --timeout-ms 15000
c11 browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000

Common Flows

Form Submit

c11 --json browser open https://example.com/signup
c11 browser surface:7 get url
c11 browser surface:7 wait --load-state complete --timeout-ms 15000
c11 browser surface:7 snapshot --interactive
c11 browser surface:7 fill e1 "Jane Doe"
c11 browser surface:7 fill e2 "[e-mail]"
c11 --json browser surface:7 click e3 --snapshot-after
c11 browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
c11 browser surface:7 snapshot --interactive

Clear an Input

c11 browser surface:7 fill e11 "" --snapshot-after --json
c11 browser surface:7 get value e11 --json

Stable Agent Loop (Recommended)

# navigate -> verify -> wait -> snapshot -> action -> snapshot
c11 browser surface:7 get url
c11 browser surface:7 wait --load-state complete --timeout-ms 15000
c11 browser surface:7 snapshot --interactive
c11 --json browser surface:7 click e5 --snapshot-after
c11 browser surface:7 snapshot --interactive

If get url is empty or about:blank, navigate first instead of waiting on load state.

Deep-Dive References

Reference	When to Use
references/commands.md	Full browser command mapping and quick syntax
references/snapshot-refs.md	Ref lifecycle and stale-ref troubleshooting
references/authentication.md	Login/OAuth/2FA patterns and state save/load
references/authentication.md#saving-authentication-state	Save authenticated state right after login
references/session-management.md	Multi-surface isolation and state persistence patterns
references/video-recording.md	Current recording status and practical alternatives
references/proxy-support.md	Proxy behavior in WKWebView and workarounds

Ready-to-Use Templates

Template	Description
templates/form-automation.sh	Snapshot/ref form fill loop
templates/authenticated-session.sh	Login once, save/load state
templates/capture-workflow.sh	Navigate + capture snapshots/screenshots

Limits (WKWebView)

These commands currently return not_supported because they rely on Chrome/CDP-only APIs not exposed by WKWebView:

• viewport emulation
• offline emulation
• trace/screencast recording
• network route interception/mocking
• low-level raw input injection

Use supported high-level commands (click, fill, press, scroll, wait, snapshot) instead.

Troubleshooting

js_error on snapshot --interactive or eval

Some complex pages can reject or break the JavaScript used for rich snapshots and ad-hoc evaluation.

Prefer get text body / get html body for reading page content; reserve eval for interaction and computed checks. eval and snapshot --interactive run injected JavaScript that strict-CSP or framebusting sites (Hacker News is a known case) reject with js_error — even for something as trivial as eval "1+1" — whereas get text/get html read the already-rendered DOM and keep working. Reach for eval when you genuinely need to run script on the page, not as the default way to extract content.

Recovery steps:

c11 browser surface:7 get url
c11 browser surface:7 get text body
c11 browser surface:7 get html body

• Use get url first so you know whether the page actually navigated.
• Fall back to get text body or get html body when snapshot --interactive or eval returns js_error.
• If the page is still failing, navigate to a simpler intermediate page, then retry the task from there.