TabBridge

TabBridge is a local-first browser execution layer for AI agents and deterministic workflows. It lets MCP clients, a CLI, or local REST callers operate the Chrome tabs you already have open, while a Chrome side panel shows every action and requires approval for sensitive operations.

TabBridge is not a chatbot and direct browser tools do not require an LLM. Optional model providers are used only for planning.

Architecture

Codex / Claude Code / custom MCP client / CLI
                    │
              MCP / REST
                    │
      daemon on 127.0.0.1:43120
      sessions · policy · logs · workflows
                    │
       authenticated local WebSocket
                    │
 Chrome MV3 extension → current Chrome tab

MVP features

• Strict, versioned Zod protocol shared by every boundary.
• Semantic snapshots and temporary element references; stale references fail closed.
• REST API, WebSocket event stream, MCP stdio server, and CLI.
• MV3 side panel with status, action timeline, approvals, pause, and emergency stop.
• Safe/review/approval-required/blocked policy decisions and secret redaction.
• JSONL audit logs and YAML workflow recording, export, and deterministic replay.
• Optional Ollama, LM Studio, OpenAI-compatible, and Anthropic providers.

Five-minute quick start

Requirements: Node.js 22 or newer, pnpm, and Chrome.

For a tester-focused walkthrough using the bundled safe fixture, see SETUP.md.

pnpm install
pnpm build
pnpm --filter @tabbridge/daemon start

The daemon generates and persists the local extension token beneath ~/.tabbridge on first start. Retrieve it locally with:

pnpm --filter @tabbridge/cli start extension token

Open chrome://extensions, enable Developer mode, choose Load unpacked, and select apps/extension/dist. Open the TabBridge side panel, enter the token, and connect.

Check the connection and inspect the current page:

pnpm --filter @tabbridge/cli start doctor
pnpm --filter @tabbridge/cli start tabs
pnpm --filter @tabbridge/cli start snapshot

Add --json to CLI commands for machine-readable output.

MCP clients

Build first, then configure an MCP stdio server with:

command: node
args: [/absolute/path/to/TabBridge/packages/mcp-server/dist/index.js]

Do not assume a particular global client configuration path. See docs/mcp-setup.md for examples for Codex, Claude Code, and generic clients.

Ollama

Create ~/.tabbridge/config.yaml:

providers:
  ollama:
    type: ollama
    baseUrl: http://127.0.0.1:11434
    model: qwen3:8b

Model configuration is optional. Browser tools remain available without it. See docs/model-providers.md.

Workflows

Every successful session records semantic actions. Export and replay without an LLM:

tabbridge workflow export <session-id>
tabbridge workflow list
tabbridge workflow run download-daily-report

See docs/workflow-format.md and examples/workflows/download-daily-report.yaml.

Security model

The daemon binds to 127.0.0.1; the extension authenticates with a locally generated token; model secrets remain daemon-side. Sensitive actions wait for explicit approval and blocked actions never reach Chrome. Page content is always marked untrusted and cannot modify runtime policy. Logs and exports redact likely credentials.

See docs/security.md before using TabBridge with sensitive accounts.

Development

pnpm dev
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build

The fixture site is local-only. Tests never target third-party production websites.

Current limitations

• Chrome only; native messaging is an extension point but the MVP transport is localhost WebSocket.
• One connected extension is the supported MVP topology.
• Semantic locators depend on the current page; snapshots must be refreshed after substantial DOM changes.
• The built-in model loop is intentionally minimal; external MCP harnesses are the primary interface.
• Chrome Web Store publication, remote daemon exposure, cookie export, CAPTCHA bypass, purchasing, and financial automation are out of scope.

Roadmap

• Harden native messaging and signed extension packaging.
• Add richer deterministic assertions and workflow migration tooling.
• Expand local fixture coverage and cross-platform installers.
• Add opt-in multi-profile routing without exposing browser credentials.

See CONTRIBUTING.md to contribute. TabBridge is licensed under Apache-2.0.