Skip to content
SpecDeck

Claude's browser

On macOS, a Claude Code session gets a browser of its own, so Claude can check the web app it builds. Claude’s browser in the user guide says how to use it; this page says how it is kept apart. You can turn it off with Give Claude a browser in Settings, for sessions you start afterwards.

How Claude's browser connects On the host's Mac, Claude Code calls the browser tools on SpecDeck's endpoint for the session, which listens on 127.0.0.1 only and needs the session's token; other programs without the token are refused. The endpoint drives a hidden, private WebKit window that cannot use SpecDeck's functions and keeps nothing. That window opens web pages, such as the app Claude is building. Browser steps and screenshots go into the session's timeline, which viewers see. Host's Mac Claude Code has the session's token in its environment SpecDeck endpoint 127.0.0.1 only /hooks /status /mcp each needs the token Claude's browser hidden, private WebKit window: no SpecDeck functions, keeps nothing Other programs without the token refused Session timeline browser steps and screenshots, which viewers see Web pages your local app, any site One browser per session. It closes with the session, and starts clean after a restart.

Only the session’s own Claude Code can use it

Section titled “Only the session’s own Claude Code can use it”

Claude Code reaches the browser through a small web server that SpecDeck starts for each session. The same server receives the events that build the session’s timeline.

  • It listens on 127.0.0.1 only, on a port the system picks, so nothing on your network can reach it. When Claude Code runs in a sandbox, it reaches the server through the sandbox’s own way to your computer, such as host.docker.internal, which arrives on 127.0.0.1 too; a sandbox or container on your computer whose network allows the port can reach it, other machines still can’t.
  • Every request needs the session’s token. The token is 32 random bytes, new for every session, and the server refuses any request to /hooks, /status or /mcp without it. Another program on your computer that finds the port still gets nothing.
  • The token is not written to disk. Claude Code gets it in its environment, as SPECDECK_HOOK_TOKEN. The settings files SpecDeck gives Claude Code, including the MCP configuration that adds the browser, contain ${SPECDECK_HOOK_TOKEN} instead of the token, and only your account can read them. They are deleted when the session ends. Started through a start command, Claude Code gets the same settings as arguments instead of files, still without the token, which the start command gets in its environment and passes into the sandbox.

Commands the agent runs inherit Claude Code’s environment, and with it the token. See Known limits.

A separate, private browser

Section titled “A separate, private browser”
  • Hidden. The browser is a WebKit window that is never shown, never takes the focus, and is not in the Window menu.
  • Private and empty. Each session’s browser starts without cookies, storage, history or logins, and shares none with your own browsers, with SpecDeck’s windows or with another session. It is like a private window that nobody can see.
  • No way into SpecDeck. A page in the browser cannot use any of SpecDeck’s functions, read its settings or sessions, or type into the agent. The app grants its functions to its own windows by name, and the browser’s windows are not among them.
  • Nothing is kept. The browser closes when the session ends, and everything it stored goes with it. If SpecDeck restarts, for example to update, the browser is gone and the next tool call starts a new, empty one.

The browser opens only http and https addresses, and that includes your own computer and your local network, because checking the app on localhost is what it is for. Pages Claude opens are input to Claude like any other: a page could hold text meant to steer the agent. Claude Code’s own permission rules are your guard against that.

Claude Code asks first

Section titled “Claude Code asks first”

SpecDeck does not approve the browser tools on your behalf, neither in the settings it gives Claude Code nor in its answers to permission requests. Claude Code treats them like any other MCP tool, under your own permission rules and mode: in the default mode it asks you before it first uses each one; in auto mode it decides itself. In rules, the tools are named mcp__specdeck__navigate, mcp__specdeck__screenshot and so on.

What viewers see

Section titled “What viewers see”

Viewers see the browser steps in the timeline, such as Opened localhost:5173/login in its browser or Clicked “Sign in”, and what Claude types into pages, as they see any other tool. Text Claude types into a password field, or into a field the page marks as a one-time code, card number or card security code, is left out of the timeline before it is sent; so is text typed into a field SpecDeck can’t identify. The terminal is not filtered: Claude Code prints each tool call there, including what Claude types. Use test accounts, not your own passwords.

Screenshots the browser takes are kept in the timeline with the page’s address, and everyone in the session sees them, including people who join later. A screenshot can show more than the terminal does. To keep them out, turn off Show screenshots in the timeline in Settings: sessions you start afterwards then only say that Claude took a screenshot. The same applies to pictures from other MCP tools, such as Playwright MCP.