Tandem Browser

Tandem Browser

Tandem Browser is a live human-AI browser environment for shared work in the user's real browser context.

Important: Tandem itself must already be running. The local API and MCP server are how an agent talks to a running Tandem instance, not alternatives to Tandem itself.

Agents work with a running Tandem instance through MCP or HTTP, depending on what the client supports in practice. For some clients, MCP is the primary or only realistic integration path.

Use this skill when the task should happen in the user's real Tandem browser instead of a sandbox browser, especially for:

• inspecting or interacting with tabs the user already has open
• working inside authenticated sites that already live in Tandem
• reading SPA state, network activity, or session-scoped browser data
• coordinating with the user without overwriting the tab they are actively using

Connecting to Tandem

Tandem supports agents on the same machine (MCP or HTTP) and on remote machines over a private Tailscale network (MCP or HTTP). Both can be active at the same time.

Discovery

A running Tandem instance publishes its own version-matched bootstrap surface. This works for both local and remote agents, and does not require repo access:

• GET /agent — human-readable bootstrap page
• GET /agent/manifest — machine-readable endpoint manifest with all route families
• GET /agent/bootstrap — authenticated bootstrap contract with runtime context, operating rules, and the agent toolbox
• GET /skill — version-matched usage guide
• GET /agent/version — version and capability summary

These routes are public (no auth required) and use the request Host header, so they return correct URLs whether accessed locally or over Tailscale on the configured Agent API port.

After pairing or reading a local token, immediately read these resources. When you have a paired binding token, include Authorization: Bearer <token> on these reads so Tandem can mark startup complete:

1. GET /skill
2. GET /agent/manifest
3. GET /agent/bootstrap with Authorization: Bearer <token>
4. GET /status
5. GET /workspaces with Authorization: Bearer <token>

Do not stop at "auth works." The bootstrap and manifest are the contract that teaches a newly connected agent how to use Tandem as a full browser layer. New paired agents that skip /skill, /agent/manifest, or /agent/bootstrap will receive 428 agent_startup_required on normal API/MCP routes until the startup reads are complete.

Practical Connection Reality

The conceptual model is simple:

1. Tandem is already running
2. the agent discovers Tandem via its bootstrap surface or this skill file
3. the agent uses MCP or HTTP to talk to the running Tandem instance

Practical notes:

• some agent clients primarily rely on MCP and may not have a practical direct HTTP calling path
• some MCP clients need a reconnect or session restart after configuration changes before the Tandem MCP server becomes visible
• MCP and HTTP are connection layers to Tandem, not substitutes for a running Tandem instance

Option 1: MCP Server (local or remote)

The MCP server exposes 257 tools with full API parity.

Same machine (stdio): Add to your MCP client configuration (e.g. ~/.claude/settings.json for Claude Code):

{
  "mcpServers": {
    "tandem": {
      "command": "node",
      "args": ["/path/to/tandem-browser/dist/mcp/server.js"]
    }
  }
}

Remote machine (Streamable HTTP over Tailscale): Pair first via Settings > Connected Agents, then configure:

{
  "mcpServers": {
    "tandem": {
      "type": "streamable-http",
      "url": "http://<tandem-tailscale-ip>:<configured-port>/mcp",
      "headers": {
        "Authorization": "Bearer <your-binding-token>"
      }
    }
  }
}

Start Tandem (npm start), and the agent can connect to the running MCP server. All MCP tools mirror the HTTP API below, so the same capabilities are available through either connection method when the client supports them.

Option 2: HTTP API (local or remote)

Use direct HTTP when the client can call the API itself. Local agents use the token from ~/.tandem/api-token. Remote agents use a binding token obtained through Tandem's pairing flow.

API_PORT="$(cat ~/.tandem/api-port 2>/dev/null || printf 8765)"
API="http://127.0.0.1:${API_PORT}"     # or http://<tailscale-ip>:<configured-port> for remote
TOKEN="$(cat ~/.tandem/api-token)"      # or binding token from pairing
AUTH_HEADER="Authorization: Bearer $TOKEN"
JSON_HEADER="Content-Type: application/json"

tab_id() {
  node -e 'const fs=require("fs"); const data=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(String(data.tab?.id ?? ""));'
}

curl -sS "$API/status"

The Agent API port defaults to 8765 and is configurable in Tandem Settings. Local clients can read the current port from ~/.tandem/api-port or the richer endpoint metadata in ~/.tandem/api-endpoints.json. Do not replace ~/.tandem/api-token; it remains the local bootstrap token contract.

Orienting yourself on connect

A Tandem instance you join may already have state — from your own earlier session, from another agent, or from the user's ongoing work.

Passive awareness first. No autonomous cleanup.

• The Default workspace belongs to the user. Don't treat it as yours.
• Other workspaces may contain leftover work from earlier agents. Do not reorganize, close, or act on tabs you did not put there, unless the user asks.
• Your session may land in a workspace with open tabs that are not from you. Just note that. You do not need to ask "what is this?" — the user will direct you when they need you.
• When the user says "this tab" or "this page", figure out which workspace THEY are focused in. Active tab is workspace-scoped, and yours may not match the user's (see Core Model below).
• Act on user intent, not on inherited state.

You are a teammate walking into a shared room. Notice. Don't rearrange.

Core Model

Workspace-scoped active tab

"Active tab" is not a single global concept in Tandem. Each workspace has its own active tab. When the agent and the user are in different workspaces (common), their active tabs differ.

• GET /active-tab/context / tandem_active_tab_context returns the active tab of the workspace your session is currently in — not necessarily what the human is looking at.
• To find what the human sees right now: iterate the tabs array in the response and find the one with active: true in the workspace where the human's latest activity is (usually Default, but not always — check actor.kind and source fields).

Targeting styles

Tandem has three targeting styles. Pick the smallest one that works.

1. Active tab: Routes like /find and the rest of /find* still act on the active tab. Some observation routes also default to the active tab when no explicit target is provided.

2. Specific tab: Many read and browser routes support X-Tab-Id: <tabId>, so background tabs no longer need to be focused just to inspect them. Current support includes /snapshot, /page-content, /page-html, /execute-js, /wait, /links, and /forms. The MCP tools mirror this via an optional tabId parameter.

3. Session partition: Session-aware routes support X-Session: <name> so you can target a named isolated session without manually tracking the partition string.

Rule of thumb: prefer explicit tabId over "active"

Even when a tool defaults to the active tab, pass tabId explicitly whenever you know which tab you mean. Benefits:

• Immune to workspace-scoping surprises — your "active" may not equal the user's "active"
• Immune to race conditions when focus changes quickly during co-browsing
• Self-documenting — the tool call records your intent, not the accident of whichever tab happened to be focused at that moment

Trust tabId, don't trust "active".

For ad hoc JS on a background tab: use X-Tab-Id on HTTP, or pass tabId to the MCP tandem_execute_js tool. User approval still gates execution regardless of tab target.

Golden Rules

Cross-Platform Development Guidance

When proposing or editing Tandem code, preserve the platform contract in docs/platform-support.md. macOS Apple Silicon is the protected baseline, Windows 11 x64 is the active target, and Linux is best effort. Do not add new platform branches in shared code; route platform-specific behavior through the src/platform/ adapter layer as it lands. Keep local agent bootstrap intact: ~/.tandem/api-token remains readable by local MCP/HTTP clients until a replacement bootstrap flow is explicitly designed and shipped. Shared helpers used by tests, MCP, or Node scripts must not require Electron app at module import time.

Current User Context

Start here when the request may refer to "this page", "the current tab", or what the user is looking at right now:

curl -sS "$API/active-tab/context" \
  -H "$AUTH_HEADER"

That returns:

• activeTab.id, url, title, and loading
• viewport state (scrollTop, scrollHeight, clientHeight)
• pageTextExcerpt for quick answers
• the full tab list with the active flag

If you need passive awareness without polling, subscribe to SSE:

curl -sS -N "$API/events/stream" \
  -H "$AUTH_HEADER" \
  -H "Accept: text/event-stream"

Useful event types: tab-focused, navigation, page-loaded.

Recommended Tab Workflow

Background helper tab

OPEN_JSON="$(curl -sS -X POST "$API/tabs/open" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"url":"https://example.com","focus":false,"source":"wingman"}')"

TAB_ID="$(printf '%s' "$OPEN_JSON" | tab_id)"

Inspect it without stealing focus:

curl -sS "$API/snapshot?compact=true" \
  -H "$AUTH_HEADER" \
  -H "X-Tab-Id: $TAB_ID"

curl -sS "$API/page-content" \
  -H "$AUTH_HEADER" \
  -H "X-Tab-Id: $TAB_ID"

Focus only if you need active-tab-only routes:

curl -sS -X POST "$API/tabs/focus" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"tabId\":\"$TAB_ID\"}"

Clean up:

curl -sS -X POST "$API/tabs/close" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"tabId\":\"$TAB_ID\"}"

Inherit app state into a helper tab

Use this when the source tab is already logged in and you need a second tab in the same app/session. Tandem will reuse the source partition and attempt to restore IndexedDB state into the new tab.

CHILD_JSON="$(curl -sS -X POST "$API/tabs/open" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"url\":\"https://discord.com/channels/@me\",\"focus\":false,\"source\":\"wingman\",\"inheritSessionFrom\":\"$TAB_ID\"}")"

CHILD_TAB_ID="$(printf '%s' "$CHILD_JSON" | tab_id)"

Inspect the inherited helper tab in the background:

curl -sS "$API/page-content" \
  -H "$AUTH_HEADER" \
  -H "X-Tab-Id: $CHILD_TAB_ID"

Workspaces for AI Agents

Use workspaces to keep autonomous or long-running agent work organized in its own area by default, without cluttering the user's current workspace.

Important: Tandem workspaces are not private silos by default. They are separate work areas inside a shared human-AI browser environment. Multiple agents and users can each have their own workspace, inspect each other's workspaces when needed, and help each other across those boundaries.

The goal is separation for clarity and coordination, not secrecy.

Default rule:

• if the agent is doing its own work, prefer the agent's own workspace
• do not take over the user's workspace unless the task explicitly belongs there or the user asks for shared work in that exact space
• assume humans and agents may hand work back and forth across workspaces, so leave clear context when escalation or review is needed

This is the preferred pattern for OpenClaw long-running work, because the agent can keep a dedicated workspace alive, open and move tabs there via API, and bring that workspace into view instantly when the user needs to take over.

Create an AI workspace:

WORKSPACE_JSON="$(curl -sS -X POST "$API/workspaces" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"name":"OpenClaw","icon":"cpu-chip","color":"#2563eb"}')"

WORKSPACE_ID="$(printf '%s' "$WORKSPACE_JSON" | node -e 'const fs=require("fs"); const data=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(String(data.workspace?.id ?? ""));')"

Open a tab directly inside a specific workspace:

OPEN_JSON="$(curl -sS -X POST "$API/tabs/open" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"url\":\"https://example.com\",\"focus\":false,\"source\":\"wingman\",\"workspaceId\":\"$WORKSPACE_ID\"}")"

TAB_ID="$(printf '%s' "$OPEN_JSON" | tab_id)"

Activate a workspace so the user can see what the agent is doing:

curl -sS -X POST "$API/workspaces/$WORKSPACE_ID/activate" \
  -H "$AUTH_HEADER"

Move an existing tab into a workspace. This route takes a webContents ID, not a Tandem tab ID:

TAB_WC_ID="$(printf '%s' "$OPEN_JSON" | node -e 'const fs=require("fs"); const data=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(String(data.tab?.webContentsId ?? ""));')"

curl -sS -X POST "$API/workspaces/$WORKSPACE_ID/tabs" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"tabId\":$TAB_WC_ID}"

Lightweight compatibility escalation with workspaceId:

curl -sS -X POST "$API/wingman-alert" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"title\":\"Captcha blocked\",\"body\":\"Please solve the challenge in the OpenClaw workspace.\",\"workspaceId\":\"$WORKSPACE_ID\"}"

Practical pattern for first run:

1. Call GET /workspaces and look for an existing agent workspace by name.
2. If it does not exist, create it with POST /workspaces.
3. Open all agent tabs with POST /tabs/open and workspaceId.
4. Keep background reads on those tabs with X-Tab-Id where possible.
5. If the agent gets blocked, prefer creating a handoff with the same workspaceId and tabId so the user lands in the right workspace and the work can resume cleanly later.

Human-Agent Handoffs

Tandem now has a first-class durable handoff system for moments where the human needs to take over, approve something, or review a result.

Use handoffs when:

• a captcha, login wall, MFA step, or approval blocks progress
• the page is weird, drifted, or ambiguous
• the task needs human judgment before continuing
• the agent has finished a review step and wants the human to inspect something
• the task should pause now and resume later cleanly

Handoff states include:

• needs_human
• blocked
• waiting_approval
• ready_to_resume
• completed_review
• resolved

Prefer a durable handoff over a transient alert when the state matters and the work should be resumable.

Compatibility note:

• POST /wingman-alert still works, but it now acts as a compatibility wrapper over the handoff system

Handoff Operating Rules

When blocked, do not just emit a generic alert and keep retrying.

Preferred pattern:

1. create or update a handoff with the exact blocker and relevant tab/workspace context
2. stop retrying blindly
3. wait for the human to mark the work ready or resume it
4. continue from the handoff state

Use handoffs especially for:

• captcha solving
• account login or 2FA
• approval decisions
• prompt-injection blocks requiring human review
• UI states where the agent is unsure what is currently true

This keeps shared work visible, durable, and resumable.

HTTP example for a durable blocker handoff:

curl -sS -X POST "$API/handoffs" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d "{\"status\":\"blocked\",\"title\":\"Captcha blocked progress\",\"body\":\"Please solve the captcha, then mark the handoff ready.\",\"reason\":\"captcha\",\"workspaceId\":\"$WORKSPACE_ID\",\"tabId\":\"$TAB_ID\",\"actionLabel\":\"Solve captcha and resume\"}"

Sessions

Named sessions are separate browser partitions. Use them when the task should be isolated from the user's default browsing state.

Create a session:

curl -sS -X POST "$API/sessions/create" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"name":"research"}'

Navigate inside it:

curl -sS -X POST "$API/navigate" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -H "X-Session: research" \
  -d '{"url":"https://example.com"}'

Read from it without switching the user's main tab:

curl -sS "$API/page-content" \
  -H "$AUTH_HEADER" \
  -H "X-Session: research"

Session state:

curl -sS -X POST "$API/sessions/state/save" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -H "X-Session: research" \
  -d '{"name":"research-state"}'

curl -sS -X POST "$API/sessions/state/load" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -H "X-Session: research" \
  -d '{"name":"research-state"}'

Same-origin fetch relay from the page context:

curl -sS -X POST "$API/sessions/fetch" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"tabId":"tab-123","url":"/api/me","method":"GET"}'

Rules for /sessions/fetch:

• keep the target URL same-origin with the tab
• prefer relative URLs
• never send Authorization, Cookie, Origin, or Referer

Snapshot and Locator Flow

GET /snapshot returns an accessibility tree with stable refs such as @e1. Use that before raw CSS selectors whenever possible. Snapshot refs now remember which tab produced them, so ref follow-up routes stay bound to that tab.

Background read:

curl -sS "$API/snapshot?compact=true" \
  -H "$AUTH_HEADER" \
  -H "X-Tab-Id: $TAB_ID"

Ref-based interaction:

curl -sS -X POST "$API/snapshot/click" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"ref":"@e2"}'

curl -sS -X POST "$API/snapshot/fill" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"ref":"@e3","value":"hello@example.com"}'

curl -sS "$API/snapshot/text?ref=@e4" \
  -H "$AUTH_HEADER"

Semantic locators are useful when you do not want to manually parse refs:

curl -sS -X POST "$API/find" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"by":"label","value":"Email"}'

curl -sS -X POST "$API/find/click" \
  -H "$AUTH_HEADER" \
  -H "$JSON_HEADER" \
  -d '{"by":"text","value":"Continue"}'

Important: /find* is still active-tab-only. Snapshot ref follow-up routes use the tab remembered by the ref, but you should refresh refs after navigation or after taking a new snapshot.

Page Analysis and Browser Actions