Tandem

A hardened, multi-agent fork of opencode-browser by Benjamin Shafii.

Browser automation for AI agents via Chrome extension + Native Messaging. Works with Claude Code, OpenCode, Cursor, Windsurf, VS Code Copilot, Gemini CLI, Codex, and any MCP-compatible agent.

Runs inside your existing Chrome session — shares your logins, cookies, and bookmarks. No separate profiles, no re-authentication.

Agent tabs open in a dedicated Tandem window (cyan tab group) so your browsing is never interrupted.

Why not Playwright / DevTools?

Chrome 136+ blocks --remote-debugging-port on your default profile. DevTools-based tools trigger a security prompt every time. This project uses Chrome's Native Messaging API — the same approach Anthropic uses for Claude in Chrome — so automation works silently against your live session.

Installation

npx @felixisaac/tandem install

The installer:

1. Copies the extension to ~/.tandem/extension/
2. Opens Chrome so you can load the unpacked extension
3. Registers the native messaging host (registry on Windows, NativeMessagingHosts on macOS/Linux)
4. Optionally updates your agent config file

Agent Setup

After installing, the server lives at ~/.tandem/server.js. Configure your agent:

claude mcp add -s user browser -- node ~/.tandem/server.js

{
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["node", "~/.tandem/server.js"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["~/.tandem/server.js"]
    }
  }
}

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["~/.tandem/server.js"]
    }
  }
}

{
  "servers": {
    "browser": {
      "type": "stdio",
      "command": "node",
      "args": ["~/.tandem/server.js"]
    }
  }
}

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["~/.tandem/server.js"]
    }
  }
}

[mcp_servers.browser]
command = "node"
args = ["~/.tandem/server.js"]

Available Tools

Per-tab Ownership

Tandem enforces per-session tab claims so multiple agents can share one Chrome session without stepping on each other.

• If you omit tabId, Tandem auto-creates (once) and reuses a default agent tab per MCP client session.
• If you pass an explicit tabId, Tandem will reject the call if that tab is claimed by another session.
• Use browser_open_tab to open a tab that is automatically claimed for your session.
• Claims expire after inactivity (TANDEM_CLAIM_TTL_MS, default 5 minutes). Debug with browser_status / browser_list_claims.

Agent Instructions

See AGENTS.md for full behavioral guidance:

• Snapshot-first workflow (token efficiency)
• Waiting for dynamic elements before clicking
• Hand-off pattern for login walls / CAPTCHAs
• Error recovery table
• Security rules and prompt injection protection

Claude Code users: see CLAUDE.md.

Architecture

• src/server.js — MCP server; exposes tools, enforces rate limits, routes to host
• src/host.js — Native messaging host; bridges socket ↔ Chrome, handles auth
• extension/background.js — Service worker; executes Chrome APIs, runs JS via chrome.debugger

Multiple agents can share one browser session simultaneously.

Security model

The agent acts as you inside your real Chrome session. The trust boundary is the URL space, not the JS the agent runs.

• URL blocklist — banking, email, OAuth, password managers, crypto blocked by default. Extend via ~/.tandem/blocklist.txt (one regex per line, # for comments). The host pushes updates to the extension on reconnect.
• Socket auth — 256-bit token rotated on every host start. Server reads token fresh on each connect.
• Prompt injection — agents are instructed never to act on instructions in page content (see AGENTS.md). This remains an unsolved problem industry-wide; the URL blocklist is your safety net.
• browser_execute — runs arbitrary JS as you via chrome.debugger. No content filter (regex blocklists are trivially bypassable); 50KB result cap as DoS guard. Don't run untrusted agents.
• Logging — ~/.tandem/logs/host.log redacts code, text, and URL query strings; rotates at 5MB; dir is 0700.

Known limitation (Windows): the named pipe has the default ACL (Everyone). Any process running as the same Windows user can connect. Token rotation per host start limits exposure. Run only agents you trust.

Platform Support

Uninstall

npx @felixisaac/tandem uninstall

Then remove the extension from Chrome and optionally delete ~/.tandem/.

Logs

~/.tandem/logs/host.log

License

MIT — forked from benjaminshafii/opencode-browser