# 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)

```bash
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

```bash
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:

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

### 2. Install dependencies

Requires **Python 3.8+** and `pip`:

```bash
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

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

To uninstall, just delete the folder:

```bash
rm -rf ai-browser
```

### Optional: JavaScript engine

```bash
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`):

```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

```bash
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