What It Does

Browser Control gives AI agents a local, policy-governed runtime for reusable Chromium browser workflows, evidence capture, filesystem reports, and helper scripts.

It does not replace Codex/Claude Code. It works with existing agents to turn repeated browser tasks into reusable Automation Packages.

| Domain | Capabilities | |--------|-------------| | 🌐 Browser | Navigate, snapshot (accessibility tree with stable @e3 refs), click, fill, hover, type, press keys, scroll, screenshot, tab management, screencast recording. Powered by Chromium/CDP via Playwright. | | 💻 Terminal | Persistent PTY sessions (open/exec/read/write/interrupt/close/resume), command execution, output capture. Cross-platform via node-pty. | | 📁 Filesystem | Structured read/write/list/move/delete/stat — policy-governed, not shell emulation. |

Every action is gated by a policy engine (safe / balanced / trusted profiles) and returns a structured ActionResult with success/failure, risk level, and optional debug evidence.

Public integration is CLI-first and MCP-first. The TypeScript API is available for embedding. The web dashboard and Electron desktop app remain experimental/internal operator surfaces until they are stable and redesigned around Automation Packages.

Not a native desktop GUI automation product. The browser path targets Chromium/CDP and semantic accessibility snapshots. It does not automate native OS windows or non-browser desktop apps.

🎬 Demos

MIMO Research Demo — AI-powered web research with MCP tools

MCP Server Demo — AI Agent controlling browser + terminal + filesystem via MCP

⚡ Quick Start

Prerequisite: Node.js >= 22

git clone https://github.com/AbdallahIsDev/browser-control.git
cd browser-control
npm install
npm run typecheck
npm run build
npm link              # Makes `bc` command globally available

Experimental npm package:

npm install -g @abdallahisdev/browser-control
bc --help

First setup:

bc setup --non-interactive --profile balanced
bc doctor
bc status
bc package list

WSL users: Run sh scripts/install_wsl_bc.sh if bc resolves to the Linux calculator instead.

Runtime data lives under %USERPROFILE%\.browser-control (Windows) or ~/.browser-control (Unix). Override with BROWSER_CONTROL_HOME.

First Workflow

# Terminal + Filesystem
bc session create demo --policy balanced
bc term exec "node --version" --json
bc fs ls . --json

# Browser
bc browser launch --port 9222 --profile default
bc browser state --json
bc browser open https://example.com --json
bc browser snapshot --json
bc browser act click "@e3" --capture-on-success --json
bc browser task run --steps='[{"action":"open","url":"https://example.com"},{"action":"state","snapshot":true}]' --json

# Auth state + profiles
bc browser profile create work --type named
bc browser auth export auth-state.json --live
bc browser auth import auth-state.json --stored

⚡ Agent Execution Model

For Codex, Hermes-like agents, OpenCode-like agents, Gemini CLI, Claude Code, and any agent that can run shell commands, use CLI-first automation:

bc status --json
bc browser state --json
bc browser open https://example.com --json
bc browser snapshot --json
bc browser act fill searchInput "Amazon" --json
bc browser act click "@e3" --capture-on-success --json
bc browser task run --steps='[{"action":"open","url":"https://example.com"},{"action":"state"}]' --json

Why CLI first:

• fewer tool calls and fewer LLM-visible requests
• compact structured ActionResult output
• same policy/audit path as MCP/API
• better batching through bc browser task run

Use MCP Lite when the client is MCP-native or cannot run CLI. Use full MCP when a task needs the complete tool surface.

🔌 MCP Server — AI Agent Integration

Browser Control exposes its full action surface as an MCP stdio server. AI agents (Claude Desktop, Codex, Cursor, etc.) can control your local browser, terminal, filesystem, workflows, packages, and operator services through it.

{
  "mcpServers": {
    "bc": {
      "command": "bc",
      "args": ["mcp", "serve"]
    }
  }
}

Tool Categories

| Category | Key Tools | |----------|----------| | Status | status, bc_status | | Session | bc_session_create, bc_session_list, bc_session_select, bc_session_status | | Browser | Short aliases such as open, snapshot, click, fill, screenshot, plus bc_browser_launch, attach, list, hover, type, press, scroll, downloads_list, drop, highlight, generate_locator, screencast_*, provider_* | | Terminal | terminal_open, terminal_exec, bc_terminal_read, write, interrupt, snapshot, list, resume, status | | Filesystem | fs_read, fs_write, fs_list, bc_fs_move, delete, stat | | Network + Vault | bc_network_rules_list, bc_network_blocked_requests, bc_vault_list | | Debug | debug_health, debug_failure_bundle, bc_debug_get_console, bc_debug_get_network | | Service | bc_service_list, bc_service_resolve | | Workflow | bc_workflow_run, status, resume, approve, cancel, events, edit_state | | Harness | bc_harness_list, find_helper, validate_helper, rollback, generate, execute | | Packages | bc_package_install, list, info, update, remove, run, eval, grant, review, review_history, eval_history |

Full tool reference: docs/mcp.md

MCP Lite

MCP Lite exposes a smaller high-level toolset for lower token overhead:

bc_status, bc_session_status, bc_browser_open, bc_browser_open_many, bc_browser_capture, bc_browser_capture_many, bc_browser_snapshot, bc_browser_click, bc_browser_fill, bc_browser_state, bc_browser_act, bc_task_run, bc_browser_tab_list, bc_fs_write_output

Set BROWSER_CONTROL_MCP_MODE=lite for Lite mode. Full MCP mode keeps the complete tool surface.

Security with MCP

MCP clients are powerful — they can run commands, read/write files, and control browser pages with your logged-in sessions. Use safe or balanced policy for untrusted agents, scope working directories, and review destructive actions.

🏗️ Architecture

browser-control/
├── src/                        # Production TypeScript
│   ├── browser/                # CDP/Playwright browser automation
│   ├── terminal/               # PTY-based native terminal
│   ├── filesystem/             # Policy-governed FS operations
│   ├── policy/                 # Risk-based policy engine
│   ├── mcp/                    # MCP server + tool registry
│   ├── runtime/                # Daemon, broker, health, scheduler
│   ├── observability/          # Debug bundles, console/network capture, recording, visual diff
│   ├── operator/               # Doctor, setup, dashboard
│   ├── providers/              # local-first browser providers; remote providers are opt-in internals
│   ├── services/               # bc:// registry and optional .localhost proxy
│   ├── security/               # credential vault, network rules, redaction
│   ├── state/                  # SQLite-backed durable state
│   ├── workflows/              # Workflow graph runtime
│   ├── harness/                # Self-healing helper registry
│   ├── packages/               # Automation package system
│   └── knowledge/              # Markdown artifact storage
├── web/                        # React 19 + Vite dashboard
├── desktop/                    # Electron wrapper
├── tests/                      # Unit, E2E, compatibility
├── docs/                       # Full documentation
├── examples/                   # Golden workflow examples
└── automation-packages/        # Example packages

Three execution paths:

• command — terminal, filesystem, process, service, and local system work
• a11y — browser accessibility snapshots with stable refs (@e3)
• low_level — CDP, DOM, network, and browser fallback

Technology stack: TypeScript, Node.js ≥22, Playwright, node-pty, SQLite, React 19, Vite, Electron 41, Zod, ws, @modelcontextprotocol/sdk.

See the full architecture: docs/architecture/source-layout.md | docs/architecture/overview.md

📚 TypeScript API

import { createBrowserControl } from "@abdallahisdev/browser-control";

const bc = createBrowserControl({ policyProfile: "balanced" });

const result = await bc.browser.open({ url: "https://example.com" });
const snapshot = await bc.browser.snapshot();
await bc.browser.click({ target: "@e3" });
await bc.browser.screenshot({ outputPath: "./page.png" });

const term = await bc.terminal.exec({ command: "node --version" });
await bc.fs.write({ path: "./output.txt", content: "hello" });
await bc.close();

Full API reference: docs/api.md

🖥️ Experimental Operator UI

Browser Control includes a token-gated local web dashboard and an Electron wrapper in the repository, but they are not the main product surface and are not positioned as stable production UI yet.

Use CLI/MCP for normal agent integration. Treat dashboard/desktop as experimental internal operator interfaces.

npm run web:dev           # Experimental dashboard dev mode
npm run web:build         # Build experimental dashboard assets
bc web open               # Internal loopback operator UI
npm run desktop:dev       # Experimental Electron wrapper

Dashboard direction is package-first: Package Library, Run Automation Package, Create Package from Successful Run, Run History, Evidence Viewer, Repair Failed Package, Permissions/Risk Review, and tool-call/time/token savings. Dashboard/Desktop remain experimental operator surfaces.

🧰 CLI Highlights

Browser Control has a broad CLI surface for both operators and agents. Common areas:

• setup, doctor, status, config
• open, snapshot, click, fill, screenshot
• browser launch|attach|list|state|act|task|provider|profile|auth
• term open|exec|read|snapshot|interrupt|resume
• fs read|write|ls|move|rm|stat
• service register|list|resolve|remove
• daemon start|stop|status|health|logs
• run and schedule for queued tasks and recurring automations
• debug, policy, knowledge, memory, report, and package/workflow commands

Full command reference: docs/cli.md

🗺️ Roadmap

| Area | Status | |------|--------| | ✅ Browser CDP automation | Stable | | ✅ Accessibility snapshots | Stable | | ✅ Native terminal (PTY) | Stable | | ✅ Filesystem operations | Stable | | ✅ Policy engine (safe/balanced/trusted) | Stable | | ✅ MCP server | Stable | | ✅ CLI (bc command) | Stable | | ✅ TypeScript API | Stable | | ✅ Service registry (bc://) | Stable | | ✅ Debug bundles + observability | Stable | | 🧪 Web dashboard (React/Vite) | Experimental/internal | | 🧪 Electron desktop app | Experimental/internal | | 🔄 Self-healing harness | Active | | ✅ Workflow graph runtime, events, helpers | Active | | ✅ Automation packages, trust review, evals | Active | | 🧪 Remote providers | Experimental/opt-in | | 🎯 Production hardening | Planned | | 🎯 Cross-platform package publishing | Planned |

See detailed roadmap: docs/specs/2026-04-20-browser-control-v1-unified-automation-roadmap.md | Production upgrade tracker: docs/production-upgrade/STATUS.md

🔒 Security

Browser Control runs with the same authority as your user account. Treat it accordingly.

• Three policy profiles: safe (denies high/critical), balanced (confirms high/critical, default), trusted (audits high, confirms critical)
• Secrets redaction: Provider tokens, credential-vault secret refs, CAPTCHA keys, OpenRouter/model keys, and Browserbase URLs are redacted from CLI/API/MCP/UI output
• MCP security: Only connect trusted agents. Use safe/balanced policy, scope working directories, avoid storing tokens in prompts
• Dedicated browser profiles: Recommended — use BROWSER_LAUNCH_PROFILE=isolated for automation

Full security documentation: SECURITY.md | docs/security.md

📖 Documentation

| Doc | Description | |-----|-------------| | Getting Started | Prerequisites, setup, first workflows | | CLI Reference | Full bc command reference | | TypeScript API | createBrowserControl() API surface | | MCP Setup & Tools | MCP server config + current tool surface | | Automation Packages | Package-first workflow model and commands | | Architecture Overview | System architecture, data flow, component map | | Source Layout | Directory structure and conventions | | Browser Behavior | Modes, profiles, CDP, remote providers | | Terminal & Filesystem | PTY sessions, FS operations | | Configuration | All config keys, env vars, runtime paths | | Security Model | Trust boundaries, policy, secrets, MCP security | | Policy Guide | Policy profiles and risk evaluation | | Troubleshooting | Common issues and solutions | | Support Matrix | Platform and feature support | | Compatibility | Semver, breaking changes, deprecation | | WSL + Windows Chrome | WSL-specific browser setup | | Examples | Copy-pasteable CLI, API, MCP examples |

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines, CODE_OF_CONDUCT.md for community standards, and docs/release-checklist.md for the release process.

📄 License

MIT — see LICENSE for details.