tykimos/cheliped-browser/browser

Agent Browser Runtime

Control Chrome via CDP. Extract Agent DOM — a compressed DOM where every interactive element gets a numeric agentId.

Setup

Run once before first use:

cd scripts && npm install && npm run build

Core Workflow: Observe-Act Loop

# 1. Navigate and observe
node scripts/cheliped-cli.mjs '[{"cmd":"goto","args":["https://example.com"]},{"cmd":"observe"}]'
 
# 2. Use agentId from observe output to interact
node scripts/cheliped-cli.mjs '[{"cmd":"fill","args":["3","search term"]},{"cmd":"click","args":["4"]},{"cmd":"observe"}]'

First call auto-launches Chrome and saves session. Subsequent calls reconnect (the reconnect is identity-checked against the browser's DevTools token, so a crashed-and-reused PID/port can't be mistaken for the original Chrome). Call close when done.

Output Envelope

Output is always a JSON array, one envelope per command, compact by default:

[{ "cmd": "goto",  "ok": true,  "result": { "url": "...", "title": "..." } },
 { "cmd": "click", "ok": false, "error": { "code": "E_STALE_ID", "message": "..." } }]

By default each command runs even if a prior one fails (per-command isolation). Error code is one of E_BAD_ARG, E_STALE_ID, E_TIMEOUT, E_BROWSER, E_UNKNOWN.

CLI flags (before the JSON argument)

Commands

target = frame index (0-based number from list-frames) or URL substring to match.

Examples

Browse and extract content

node scripts/cheliped-cli.mjs '[{"cmd":"goto","args":["https://news.ycombinator.com"]},{"cmd":"observe"}]'

Fill a form and submit

node scripts/cheliped-cli.mjs '[{"cmd":"observe"},{"cmd":"fill","args":["7","hello"]},{"cmd":"click","args":["8"]}]'

Semantic action (login, search)

node scripts/cheliped-cli.mjs '[{"cmd":"goto","args":["https://example.com/login"]},{"cmd":"actions"}]'
node scripts/cheliped-cli.mjs '[{"cmd":"perform","args":["login-form"],"params":{"email":"user@example.com","password":"pass"}}]'

Concurrent sessions

node scripts/cheliped-cli.mjs --session agent1 '[{"cmd":"goto","args":["https://site-a.com"]}]'
node scripts/cheliped-cli.mjs --session agent2 '[{"cmd":"goto","args":["https://site-b.com"]}]'

Interact with shadow DOM content (e.g. Cloudflare Turnstile, web components)

# 1. Discover shadow DOM hosts and their contents
node scripts/cheliped-cli.mjs '[{"cmd":"observe-shadow"}]'
 
# 2. Click element inside shadow DOM (pierces shadow boundaries recursively)
node scripts/cheliped-cli.mjs '[{"cmd":"click-deep","args":["input[type=checkbox]"]}]'
 
# 3. Use ">>>" to explicitly cross shadow DOM boundaries
node scripts/cheliped-cli.mjs '[{"cmd":"click-deep","args":["#turnstile-widget >>> input[type=checkbox]"]}]'
 
# 4. Fill input inside shadow DOM
node scripts/cheliped-cli.mjs '[{"cmd":"fill-deep","args":["#shadow-host >>> input[name=email]","user@example.com"]}]'

click-deep and fill-deep use absolute coordinate dispatch for real mouse events. Plain selectors auto-search all shadow roots recursively. Use >>> to target specific shadow host → inner element paths.

Interact with iframe content (e.g. Cloudflare Turnstile, CAPTCHA, embedded widgets)

# 1. List all iframes on the page
node scripts/cheliped-cli.mjs '[{"cmd":"list-frames"}]'
 
# 2. Observe elements inside iframe at index 0
node scripts/cheliped-cli.mjs '[{"cmd":"observe-frame","args":["0"]}]'
 
# 3. Click a checkbox inside the iframe (use CSS selector from observe-frame output)
node scripts/cheliped-cli.mjs '[{"cmd":"click-frame","args":["0","input[type=checkbox]"]}]'
 
# Or match iframe by URL substring instead of index
node scripts/cheliped-cli.mjs '[{"cmd":"click-frame","args":["turnstile","input[type=checkbox]"]}]'

The iframe commands use absolute coordinate dispatch (iframe position + element position) to produce real mouse events that pass bot detection.

Key Notes

• Call observe before click/fill — agentIds are only valid after observation.
• fill works with React/SPA apps (uses native input value setters).
• Agent DOM is token-compressed — far fewer tokens than raw HTML.
• Chrome persists between calls until close. No restart needed.
• Output is always a JSON array of { cmd, ok, result|error } envelopes (see Output Envelope above); compact by default, --pretty to indent.
• click scrolls the target into view and validates its box before dispatching, so off-screen / zero-area elements don't produce a silent no-op.
• For shadow DOM content (Cloudflare Turnstile, web components): use observe-shadow → click-deep/fill-deep. Supports >>> syntax to pierce shadow boundaries.
• For iframe content (embedded widgets): use list-frames → observe-frame → click-frame/fill-frame. Regular observe/click cannot interact with iframe elements.
• list-frames also discovers iframes hidden inside shadow DOM.