ai-browser

A full-featured terminal browser that an AI can completely control — navigate, read pages, log in, sign up, handle 2FA, generate disposable emails, store credentials, download files, and replay whole processes — from any MCP-capable agent (opencode, Claude Desktop, etc.). Humans get an interactive terminal CLI too.

No UI needed: it renders pages to plain text with numbered LINKS and FORMS so an AI can act on [3] or 1.2 without a DOM. It works with plain HTML (fast, zero heavy deps) and can optionally upgrade to a real headless Chromium engine when Playwright is available.

Features

Browser core

• Persistent session: cookies and history saved to ~/.ai-browser/, logins survive restarts.
• Deterministic addressing: pages render to text with numbered LINKS and FORMS; the AI acts by index (3, 1.2) or by name/id/CSS.
• Multiple tabs, each with its own history, one shared session.
• Page cache (LRU) — back/forward/reload are instant.
• Retry-with-backoff and gzip on all requests for speed and reliability.
• Proxy support (http://, socks5://).

AI agent tools (55 via MCP)

• Navigation: navigate, read_page, back/forward/reload, history, tabs, wait, wait_for_text, find_text, screenshot (JS mode), save/download/fetch.
• Forms: fill, check, select, submit, click, extract, extract_json.
• Auth: auto_login, auto_signup (auto-detects email/name/password/confirm fields), analyze_page (detects login/signup/CAPTCHA/2FA).
• Credential vault: save_credentials, get_credentials, list/delete, auto_login_vault — passwords obfuscated on disk.
• Disposable email (mail.tm API): create inbox, list messages, read, extract verification codes — so signups that need an email address work.
• Macros: record a whole process once, replay anywhere, with conditional steps (if_contains, goto, stop).
• Detection: CAPTCHA and 2FA/OTP pages are flagged so the AI knows a human step is required.

JavaScript (optional)

enable_js() upgrades to Playwright + Chromium headless for JS-only sites:

• pip install playwright && playwright install chromium
• (On Termux/Android use termux-x11; on desktop it works out of the box.)

Try it offline (no internet needed)

python demo_server.py        # terminal 1: a tiny login-protected site on :8080
python cli.py http://127.0.0.1:8080/login   # terminal 2: human browser
# login: admin / secret   (or emma / secret)

Or let the AI do the whole flow through MCP: navigate → signup → fetch → login → vault → email → macro.

Download & Install

1. Download the code

git clone https://github.com/void-builder-1/ai-browser.git
cd ai-browser

Or download the ZIP from GitHub: Code → Download ZIP, then unzip:

unzip ai-browser-main.zip
cd ai-browser-main

2. Install dependencies

Requires Python 3.8+ and pip:

pip install -r requirements.txt

(On Termux/Android: pkg install python && pip install -r requirements.txt. If pip is blocked system-wide, use a virtualenv: python -m venv venv && source venv/bin/activate.)

3. Run

python cli.py            # human terminal browser
python cli.py https://example.com   # open a URL directly

To uninstall, just delete the folder:

rm -rf ai-browser

Optional: JavaScript engine

pip install playwright && playwright install chromium

(On Termux/Android use termux-x11; on desktop it works out of the box.)

Let the AI drive it

With opencode

Add to opencode.json (project or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "aibrowser": {
      "type": "local",
      "command": ["python3", "/absolute/path/to/aibrowser/mcp_server.py"]
    }
  }
}

Restart opencode, then tell it: "use the aibrowser MCP server to sign up on example.com and do X".

With any other MCP client

Point the client at aibrowser/mcp_server.py (stdio transport). 55 tools are exposed — the full list comes from tools/list, but the main workflow tools:

tool	purpose
navigate(url)	open a URL, returns text snapshot
read_page()	readable text + numbered links + forms
auto_login(u, p) / auto_signup(email, pass, name)	one-shot auth
fill / check / select / submit / click	drive forms
save_credentials / get_credentials / auto_login_vault	vault
email_create / email_messages / email_read / email_code	disposable mail
analyze_page()	login/signup/CAPTCHA/2FA detection
record_start / record_stop / macro_run	reusable processes
enable_js / screenshot / set_proxy / status	advanced

The AI workflow pattern

1. navigate("https://target-site.com/signup")
2. analyze_page() → see the form structure and any 2FA/CAPTCHA
3. email_create() → get a disposable address for the signup
4. auto_signup(email, "Str0ng!pass", "Alice")
5. email_messages() + email_code(msg_id) → read the verification email
6. fill("1.1", code) + submit("1") → finish verification
7. save_credentials(site, email, pass) → store for next time
8. get_cookies() to confirm the session; cookies persist on disk

CLI commands

open, links, forms, click, fill, check, select, submit, login, signup, analyze, vault/vaultsave/vaultget/vaultdel/ vlogin, mail/mailmsgs/mailread/mailcode, fetch, find, waitfor, cache, save, download, grab, grabjson, record, stop, run, macros, back, fwd, reload, cookies, clearcookies, history, js, shot, proxy, status, raw, url, title, help, quit.

Tests

python test_engine.py    # 37 checks: nav, auth, vault, tabs, macros, cache...

Limitations

• No JavaScript unless you install Playwright (then enable_js()).
• CAPTCHAs are detected and flagged for the AI, not solved automatically.
• 2FA codes are read from the disposable inbox when the site emails them.

License

MIT