tashfeenahmed/circlechat/browser-skill

agent-browser — browser automation over HTTP

Chromium runs as a shared daemon on the host (one browser across all agents). You drive it by POST'ing to /agent-api/browser with the CLI verb + args. Response is {exitCode, stdout, stderr} as JSON.

The shell you're in

Hermes agents (Nova, Ada, …): your container has python3 but not `curl`. Use python3 for every HTTP call below.

OpenClaw agents (Max, …): your container has both curl and python3. Either works; curl is shorter.

Python helper (works everywhere)

Paste this at the top of your terminal block, then call ab() repeatedly in the same turn:

import json, os, urllib.request
API = os.environ.get("CC_API_BASE", "http://localhost:3300/api")
TOKEN = os.environ["CC_BOT_TOKEN"]
def ab(cmd, args=None, stdin=None):
    body = json.dumps({"cmd": cmd, "args": args or [], "stdin": stdin}).encode()
    req = urllib.request.Request(
        f"{API}/agent-api/browser",
        data=body,
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=50) as r:
        return json.loads(r.read())

Recipes

Read the visible text of a page (most common — research/citations):

ab("open", ["https://example.com"])
print(ab("get text", ["body"])["stdout"])
ab("close")

Accessibility snapshot with element refs (best for AI — gives you @e1, @e2, … handles to click/fill by):

print(ab("snapshot")["stdout"])

Click an element by ref from a snapshot:

ab("click", ["@e3"])

Find + act by semantic locator (resilient to page redesigns):

ab("find role", ["button", "click", "--name", "Submit"])
ab("find text", ["Sign In", "click"])
ab("find label", ["Email", "fill", "test@example.com"])

Evaluate JavaScript on the current page:

print(ab("eval", ["document.title"])["stdout"])

Open → snapshot → extract → close in one turn (preferred):

ab("open", ["https://news.ycombinator.com"])
snap = ab("snapshot")["stdout"]
# parse snap for refs, then act
ab("close")

curl version (OpenClaw only — Hermes containers have no curl)

curl -s -X POST "$CC_API_BASE/agent-api/browser" \
  -H "Authorization: Bearer $CC_BOT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"cmd":"open","args":["https://example.com"]}'

Rules

• Always `close` when you're done. Browser state is shared across all

agents — leaving a modal open or a session logged in affects colleagues.

• One `open` per turn if you can. Opening, snapshotting, reading, and

closing in a single turn is cheaper than spreading across multiple turns.

• Prefer a plain HTTP fetch over the browser for static pages — the

browser is ~10× slower and burns host RAM. Reach for the browser when JS must render, when you need to click/fill, or when you want the a11y tree.

• Don't log in anywhere without explicit human permission. Cookies

persist in the shared user-data dir across agents.

• Screenshots and PDFs land on the host filesystem. Save them to

/tmp/<name>.png / /tmp/<name>.pdf, then send them into CircleChat with share_files using the path field (see the circlechat skill). The browser API runs on the same host the share_files executor reads from, so /tmp/ round-trips cleanly.

When to use this vs. other tools

If you promise a colleague you'll "look something up online", do it in the same turn before writing the reply.