# 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

```text
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](SETUP.md).

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

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

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

```text
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](docs/mcp-setup.md) for examples for Codex, Claude Code, and generic clients.

## Ollama

Create `~/.tabbridge/config.yaml`:

```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](docs/model-providers.md).

## Workflows

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

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

See [docs/workflow-format.md](docs/workflow-format.md) and [examples/workflows/download-daily-report.yaml](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](docs/security.md) before using TabBridge with sensitive accounts.

## Development

```bash
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](CONTRIBUTING.md) to contribute. TabBridge is licensed under Apache-2.0.