Unbrowse — Drop-in Browser Replacement for Agents

Browse once, cache the APIs, reuse them instantly. First call discovers and learns the site's APIs (~20-80s). Every subsequent call uses cached skills (<200ms for server-fetch, ~2s for sites requiring browser execution).

IMPORTANT: Always use the CLI (bun src/cli.ts). NEVER pipe output to node -e, python -c, or jq — this causes shell escaping failures. Use --path, --extract, and --limit flags instead.

Server Startup

CODEBLOCK0

If not running, the CLI auto-starts the server. First time requires ToS acceptance — ask the user:

Unbrowse needs you to accept its Terms of Service:

• - Discovered API structures may be shared in the collective registry
• You will not use Unbrowse to attack, overload, or abuse any target site

Full terms: https://unbrowse.ai/terms

After consent, the CLI handles startup automatically. First run also needs the browser engine:

CODEBLOCK1

Core Workflow

Step 1: Resolve an intent

CODEBLOCK2

This returns available_endpoints — a ranked list of discovered API endpoints. Pick the right one by URL pattern (e.g., MainFeed for feed, HomeTimeline for tweets).

Step 2: Execute with extraction

CODEBLOCK3

This is the key pattern — --path + --extract + --limit replace ALL piping to jq/node/python.

Step 3: Submit feedback (MANDATORY)

CODEBLOCK4

Rating: 5=right+fast, 4=right+slow(>5s), 3=incomplete, 2=wrong endpoint, 1=useless.

Data Extraction Flags

These flags eliminate the need to pipe output to any external parser:

When these flags are used, trace metadata is slimmed automatically (1MB raw -> 1.5KB output typical).

Examples

CODEBLOCK5

Extraction Recipes

For responses you parse repeatedly, submit a recipe so future calls return clean data automatically (for ALL agents):

CODEBLOCK6

When a recipe exists, future executions auto-return clean data. Use --raw to bypass recipes.

Authentication

Automatic. Unbrowse extracts cookies from your Chrome/Firefox SQLite database — if you're logged into a site in Chrome, it just works.

If auth_required is returned:

CODEBLOCK7

User completes login in the browser window. Cookies are stored and reused automatically.

Other Commands

CODEBLOCK8

Mutations

Always --dry-run first, ask user before --confirm-unsafe:

CODEBLOCK9

REST API Reference

For cases where the CLI doesn't cover your needs, the raw REST API is at http://localhost:6969:

Rules

1. 1. Always use the CLI — never pipe to node -e, python -c, or jq. Use --path/--extract/--limit instead.
2. Always try resolve first — it handles the full marketplace search -> capture pipeline
3. Check the result — if wrong, pick from available_endpoints and re-execute with INLINECODE51
4. If auth_required, use login then retry
5. Always --dry-run before mutations
6. Always submit feedback after every resolve call — this is mandatory
7. If the response is deeply nested, submit a recipe so future agents get clean data
8. Report bugs and issues on GitHub — when something breaks, is slow, or behaves unexpectedly, file an issue:

   gh issue create --repo unbrowse-ai/unbrowse \
     --title "bug: {short description}" \
     --body "## What happened\n{description}\n\n## Expected\n{what should have happened}\n\n## Context\n- Skill: {skill_id}\n- Endpoint: {endpoint_id}\n- Domain: {domain}\n- Error: {error message or status code}"