use-browser

POSIX-friendly (bash) browser control built on Bun/TypeScript with no built-in LLM. Run a daemon once, then issue commands (navigate, click, input, scroll, wait, snapshot) against persistent sessions. Snapshots return DOM-focused context—tab metadata, pagination hints, indexed interactive elements, and text previews—optimized for shell-driven automation instead of screenshots.

Quick start

1. Install dependencies:

bun install

2. Start the daemon (runs on 127.0.0.1:3030 by default):

bunx use-browser daemon

3. Create a session:

bunx use-browser session start
# -> { "sessionId": "...", "headless": true }

4. Drive the browser:

# Navigate
bunx use-browser navigate <sessionId> https://example.com
# Click by element index
bunx use-browser click <sessionId> 0
# Type into an element
bunx use-browser input <sessionId> 1 "hello world"
# Scroll
bunx use-browser scroll <sessionId> --pages 1.5 --direction down
# Wait
bunx use-browser wait <sessionId> --seconds 2
# Snapshot (DOM-first format)
bunx use-browser snapshot <sessionId>

5. Close the session:

bunx use-browser session close <sessionId>

Snapshot format (abridged)

{
  "snapshot": {
    "url": "https://example.com",
    "title": "Example Domain",
    "tabs": [{ "url": "...", "title": "...", "isActive": true }],
    "pageInfo": { "pagesAbove": 0, "pagesBelow": 0.4, "totalPages": 1.4 },
    "elements": [
      { "index": 0, "tag": "a", "role": "link", "text": "More information...", "href": "..." }
    ],
    "contentPreview": "Example Domain..."
  }
}

Interactive elements are indexed and tagged directly in the DOM so downstream tools can reference them deterministically (no screenshots required).

Daemon API (JSON over HTTP)

• POST /sessions { "headful": false } -> { "sessionId": "...", "headless": true }
• GET /sessions -> { "sessions": [{ "id": "...", "url": "..." }] }
• POST /command with { "action": "...", "sessionId": "...", "params": { ... } }
  • Actions: navigate {url}, click {index}, input {index,text}, scroll {pages?,direction?}, wait {seconds}, snapshot {}, close {}

Set USE_BROWSER_API to point the CLI at a remote/forwarded daemon if needed; set USE_BROWSER_PORT before launching the daemon to change the listen port.

Notes

• Headful mode: bunx use-browser session start --headful
• The daemon reuses a single Chromium instance and spawns isolated contexts per session.
• No LLMs are bundled—pair this CLI with any orchestrator that can run shell commands.
• See docs/LLM_USAGE.md for an LLM-targeted quick reference.