browse

name	browse
version	1.0.0
description	Fast web browsing for Codex via persistent headless Chromium daemon. Navigate to any URL, read page content, click elements, fill forms, run JavaScript, take screenshots, inspect CSS/DOM, capture console/network logs, and more. ~100ms per command after first call. Use when you need to check a website, verify a deployment, read docs, or interact with any web page. No MCP, no Chrome extension — just fast CLI.
allowed-tools	["Bash","Read"]

gstack: Persistent Browser for Codex

Codex Port Notes

• This port lives at ~/.codex/skills/browse.
• Use the compiled binary via shell commands: ~/.codex/skills/browse/dist/browse.
• Codex does not use slash commands. Treat requests to browse a live site, verify UI flows, or QA a deployment as the trigger for this skill.
• When local browser automation is needed, prefer this skill over plain HTTP fetches because it can click, fill forms, inspect console/network logs, and preserve session state.

Persistent headless Chromium daemon. First call auto-starts the server (~3s). Every subsequent call: ~100-200ms. Auto-shuts down after 30 min idle.

SETUP (run this check BEFORE any browse command)

Before using any browse command, find the skill and check if the binary exists:

# Check the user-level Codex install
if test -x ~/.codex/skills/browse/dist/browse; then
  echo "READY"
else
  echo "NEEDS_SETUP"
fi

Set B=~/.codex/skills/browse/dist/browse and use it for all commands.

If NEEDS_SETUP:

1. Run the one-time build in the skill directory:

cd ~/.codex/skills/browse && ./setup

2. If bun is not installed, tell the user to install it: curl -fsSL https://bun.sh/install | bash

Once setup is done, it never needs to run again (the compiled binary persists).

IMPORTANT

• Use the compiled binary via Bash: ~/.codex/skills/browse/dist/browse.
• The browser persists between calls — cookies, tabs, and state carry over.
• The server auto-starts on first command. No setup needed.

Quick Reference

B=~/.codex/skills/browse/dist/browse

# Navigate to a page
$B goto https://example.com

# Read cleaned page text
$B text

# Take a screenshot (then Read the image)
$B screenshot /tmp/page.png

# Snapshot: accessibility tree with refs
$B snapshot -i

# Click by ref (after snapshot)
$B click @e3

# Fill by ref
$B fill @e4 "[e-mail]"

# Run JavaScript
$B js "document.title"

# Get all links
$B links

# Click by CSS selector
$B click "button.submit"

# Fill a form by CSS selector
$B fill "#email" "[e-mail]"
$B fill "#password" "abc123"
$B click "button[type=submit]"

# Get HTML of an element
$B html "main"

# Get computed CSS
$B css "body" "font-family"

# Get element attributes
$B attrs "nav"

# Wait for element to appear
$B wait ".loaded"

# Accessibility tree
$B accessibility

# Set viewport
$B viewport 375x812

# Set cookies / headers
$B cookie "session=abc123"
$B header "Authorization:Bearer token123"

Command Reference

Navigation

browse goto <url>         Navigate current tab
browse back               Go back
browse forward            Go forward
browse reload             Reload page
browse url                Print current URL

Content extraction

browse text               Cleaned page text (no scripts/styles)
browse html [selector]    innerHTML of element, or full page HTML
browse links              All links as "text → href"
browse forms              All forms + fields as JSON
browse accessibility      Accessibility tree snapshot (ARIA)

Snapshot (ref-based element selection)

browse snapshot           Full accessibility tree with @refs
browse snapshot -i        Interactive elements only (buttons, links, inputs)
browse snapshot -c        Compact (no empty structural elements)
browse snapshot -d <N>    Limit depth to N levels
browse snapshot -s <sel>  Scope to CSS selector

After snapshot, use @refs as selectors in any command:

browse click @e3          Click the element assigned ref @e3
browse fill @e4 "value"   Fill the input assigned ref @e4
browse hover @e1          Hover the element assigned ref @e1
browse html @e2           Get innerHTML of ref @e2
browse css @e5 "color"    Get computed CSS of ref @e5
browse attrs @e6          Get attributes of ref @e6

Refs are invalidated on navigation — run snapshot again after goto.

Interaction

browse click <selector>        Click element (CSS selector or @ref)
browse fill <selector> <value> Fill input field
browse select <selector> <val> Select dropdown value
browse hover <selector>        Hover over element
browse type <text>             Type into focused element
browse press <key>             Press key (Enter, Tab, Escape, etc.)
browse scroll [selector]       Scroll element into view, or page bottom
browse wait <selector>         Wait for element to appear (max 10s)
browse viewport <WxH>          Set viewport size (e.g. 375x812)

Inspection

browse js <expression>         Run JS, print result
browse eval <js-file>          Run JS file against page
browse css <selector> <prop>   Get computed CSS property
browse attrs <selector>        Get element attributes as JSON
browse console                 Dump captured console messages
browse console --clear         Clear console buffer
browse network                 Dump captured network requests
browse network --clear         Clear network buffer
browse cookies                 Dump all cookies as JSON
browse storage                 localStorage + sessionStorage as JSON
browse storage set <key> <val> Set localStorage value
browse perf                    Page load performance timings

Visual

browse screenshot [path]       Screenshot (default: /tmp/browse-screenshot.png)
browse pdf [path]              Save as PDF
browse responsive [prefix]     Screenshots at mobile/tablet/desktop

Compare

browse diff <url1> <url2>      Text diff between two pages

Multi-step (chain)

echo '[["goto","https://example.com"],["snapshot","-i"],["click","@e1"],["screenshot","/tmp/result.png"]]' | browse chain

Tabs

browse tabs                    List tabs (id, url, title)
browse tab <id>                Switch to tab
browse newtab [url]            Open new tab
browse closetab [id]           Close tab

Server management

browse status                  Server health, uptime, tab count
browse stop                    Shutdown server
browse restart                 Kill + restart server

Speed Rules

1. Navigate once, query many times. goto loads the page; then text, js, css, screenshot all run against the loaded page instantly.
2. Use snapshot -i for interaction. Get refs for all interactive elements, then click/fill by ref. No need to guess CSS selectors.
3. Use js for precision. js "document.querySelector('.price').textContent" is faster than parsing full page text.
4. Use links to survey. Faster than text when you just need navigation structure.
5. Use chain for multi-step flows. Avoids CLI overhead per step.
6. Use responsive for layout checks. One command = 3 viewport screenshots.

When to Use What

Task	Commands
Read a page	goto <url> then text
Interact with elements	snapshot -i then click @e3
Check if element exists	js "!!document.querySelector('.thing')"
Extract specific data	js "document.querySelector('.price').textContent"
Visual check	screenshot /tmp/x.png then Read the image
Fill and submit form	snapshot -i → fill @e4 "val" → click @e5 → screenshot
Check CSS	css "selector" "property" or css @e3 "property"
Inspect DOM	html "selector" or attrs @e3
Debug console errors	console
Check network requests	network
Check local dev	goto http://127.0.0.1:3000
Compare two pages	diff <url1> <url2>
Mobile layout check	responsive /tmp/prefix
Multi-step flow	echo '[...]' | browse chain

Architecture

• Persistent Chromium daemon on localhost (port 9400-9410)
• Bearer token auth per session
• State file: /tmp/browse-server.json
• Console log: /tmp/browse-console.log
• Network log: /tmp/browse-network.log
• Auto-shutdown after 30 min idle
• Chromium crash → server exits → auto-restarts on next command