Tandem Browser: putting an agent inside a real Chromium profile, not beside it

The agent joins your session instead of starting a new one

The core claim is a shift of location, not of capability. The description calls Tandem a local-first Electron browser that moves the AI from a sidebar next to your browser into the browser itself, with the same tabs, the same cookies, the same logged-in sessions and the same page you are looking at right now.

That framing decides which problems it solves. The README lists automating real SaaS without an API first, naming Gmail, Coolblue, Funda, a bank's portal and an internal admin tool, on the reasoning that if you can use it in a browser, the agent can use it in Tandem in your real logged-in session. No per-site recipes have to be authored and there is no retrain-per-flow phase, which the README calls cold-start usable.

The second capability follows from the same position. Because the agent is in the page, it can rewrite the live UI of the site you are on, so a request to add a price-per-square-meter column to a listing view becomes a userscript injected into the real page while you keep scrolling.

The third is observation. The agent reads the accessibility tree and the DOM, watches the live network, and has DevTools access, which lets it answer what API the page just called and what came back, and the README notes this happens without anything leaving your machine.

This is aimed at a person who is already logged into a dozen sites and wants an agent to work inside that reality. It is not aimed at test automation.

257 tools, exposed identically over MCP and HTTP

The tool surface is where the project's scope becomes clear. The README carries a table that breaks the 257 tools into seventeen categories, and the totals are worth reading because they show what an agent is allowed to do here.

Navigation and input account for 10 tools, tabs and workspaces for 13, page content for 8, accessibility snapshots for 7, DevTools for 12 and the network inspector for 9. Sessions and auth is 12, bookmarks and history is 15, passwords and forms is 9, extensions is 13, workflows and tasks is 18, previews 4, media and UI 19, device emulation 4, data and config 16, system 6, and awareness 2. The README states that the 257 tools have full parity with the HTTP API.

The category that most affects trust is Sessions and Auth, which covers isolated sessions, a session fetch relay and auth state detection. The one that most affects cost is Media and UI at 19 tools, including voice, audio and screenshots. The one that most affects predictability is Workflows and Tasks at 18, covering multi-step workflows, task approval, agent autonomy and tab locks.

The connection model is deliberately open. Tandem is model-agnostic and any agent that speaks MCP or HTTP works, which the README lists as Claude, GPT, Gemini, a local Ollama model, LM Studio and custom scripts. Agents connect on the same machine or remotely over Tailscale, and multiple agents can share one browser. Onboarding happens in-product through Settings, then Connected Agents.

An eight layer perimeter around a page that can instruct the agent

The security reasoning here is the most important thing in the README, and it is stated as a premise rather than a feature list.

The claim is that an eight-layer security perimeter sits between web content and the agent layer, with the reason given directly: when an AI has access to a real browser, a hidden instruction in a page is remote code execution without an exploit. That is an accurate description of the threat model. A prompt injection delivered as text on a page, read by an agent that can then fill forms and click buttons in a logged-in session, is a complete compromise path that needs no software vulnerability at all.

The repository layout backs the seriousness of the claim. There is a SECURITY.md, a src/security/ path with its own test suite, a separate vitest run for src/security/tests/ and another for src/extensions/tests/, plus a CodeQL workflow and a verify workflow. There is also an AGENTS.md, an ARCHITECTURE.md, a CLAUDE.md, a PROJECT.md, a TODO.md, a COVERAGE-BASELINE.md and a skill/ directory, which is a lot of written governance for a browser project.

What the README does not do is enumerate the eight layers. If the perimeter is the reason you are considering this project, that list is the first thing to look for, in SECURITY.md and ARCHITECTURE.md, before you connect a real agent to a real account.

Building and running from the repository

There is no install command documented in what is written here, so the practical route is the repository itself: clone it, install, and use the scripts in package.json. The project is TypeScript on Electron and requires Node 20 or newer, and the version in the manifest is 1.11.4 with the main entry at dist/main.js.

The scripts cover the whole loop. Compiling is tsc plus a preload bundle, building adds electron-builder on top, and the dev and start scripts both run the same launcher.

    "dev": "node scripts/start.js",
    "start": "node scripts/start.js",
    "compile": "tsc && npm run bundle:preload",
    "watch": "tsc -w",
    "build": "tsc && npm run bundle:preload && electron-builder",

The MCP server has its own entry point, so an agent connects against a built artifact rather than the source tree.

    "mcp": "node dist/mcp/server.js",

One script deserves attention because it will fire on install. The postinstall hook rebuilds a native module against Electron's ABI, and the same command is available by hand as rebuild.

    "postinstall": "electron-rebuild -f -w better-sqlite3",
    "rebuild": "electron-rebuild -f -w better-sqlite3",

better-sqlite3 is a native dependency, so this step is what makes it load inside Electron rather than plain Node. If it fails, the browser will not start, so it is the first thing to check when a fresh clone misbehaves.

Verification is a single command that compiles, lints, runs the tests and then runs a consistency check, and there is a separate startup smoke test for a quick sanity check.

    "verify": "npm run compile && npm run lint && npm test && npm run check-consistency",
    "smoke:startup": "node tests/smoke/startup-smoke.js",

Why the project argues against Playwright

The README has a section titled Why Not Just Use Playwright, and the distinction it draws is the clearest statement of intent in the document.

Playwright gives you a headless browser that you control. Tandem gives you the user's real browser, with their tabs, sessions, cookies and extensions, and the agent joins what is already there rather than starting from scratch. That is the whole difference, and it decides which tool fits which job.

For automated tests, a controlled browser is what you want. Determinism, a clean profile, a known state before each test. Tandem is deliberately the opposite, because a real session is exactly what a test harness cannot give you. A script that logs into a banking portal, reads a statement and files a form is not a test, it is a task, and tasks run against real sessions.

The README also spends effort on what Tandem is not. It is not an AI sidebar, since a chat panel next to a browser still leaves the AI outside the page. It is not RPA or pixel automation, because there are no brittle coordinates and no record-and-replay macros; the agent works with structure. It is not screenshot-driven automation, since screenshot loops are slow, fragile and expensive and Tandem hands the agent the page as semantic structure first. And it is not a cloud service, because there is no Tandem backend: the browser, the machine, the sessions and the data are yours.

That last point is a real architectural commitment, and it is also what makes the Tailscale option and the fully offline local model option coherent rather than bolted on.

The limits of a browser that cannot be scripted the usual way

There are honest costs to the design.

The first is determinism. Nothing about a real browser with a real session is reproducible. If your requirement is a repeatable pipeline that runs unattended for a hundred runs and produces the same result, this is the wrong tool, and Playwright or any controlled harness is the right one. Tandem is built for work where a person is in the loop and hands the agent back when a CAPTCHA appears or a decision needs judgement.

The second is blast radius. The whole point is that the agent operates in sessions you are already logged into, which means a misdirected agent can act as you in your bank, your mail and your internal tools. The eight-layer perimeter is the answer to that, and the presence of a security test suite and a SECURITY.md shows the authors take it seriously, but the mitigation is architectural rather than absolute. A CAPTCHA, by the README's own example, is a point where the agent must hand back to a human, which means the design already assumes a human is watching.

The third is the maintenance surface. An Electron app bundling a Chromium build has to track upstream releases, and the browser APIs an agent depends on are internal and prone to moving. The topic list includes hermes, openclaw, claude-code, claude-desktop and codex, which suggests the agent integrations are the volatile part.

The fourth is release cadence. The recent releases include v1.10.0 in May 2026, v1.0.0 as the first binary release in April 2026 and v0.75.0 before that, while the manifest already says 1.11.4. The last push was on 2026-10-18, so the branch is ahead of the last tag. The licence is MIT and there is no cloud dependency, so a fork is entirely feasible if you need to pin a known-good state.

Editorial conclusion

Adopt Tandem Browser if your work depends on authenticated web apps that have no API and you want an agent to drive them in your existing session rather than a scripted headless run. Do not adopt it if you need a deterministic test harness, because the design trades repeatability for a live browser, and note that the packaged version is 1.11.4 while the last tagged release was v1.10.0, so pin what you install and read SECURITY.md before pointing an agent at a banking session.

Frequently asked questions

Official sources

1. hydro13/tandem-browser on GitHub
2. License: MIT
3. Project website
4. README
5. Releases