# Attach to Existing Browser

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

By default, `new_session` launches a fresh Chromium browser. If you want your coding agent to interact with a browser you already have open — with existing login state, cookies, tabs, and extensions — attach to it instead.

::: tip Simpler alternative
For most cases, a [persistent Chrome profile](/local/browser-automation#use-a-persistent-chrome-profile) is simpler and doesn't require any setup. Use the approaches below only when you need to interact with a browser that's already running.
:::

## Option 1: Chrome Extension Relay (recommended)

The Shiplight Chrome extension acts as a relay between your agent and your real Chrome browser. Once configured, your agent can auto-discover tabs — no URL or per-session setup needed.

```
Attach to my browser and check if the payment form
on the current page has any console errors.
```

### Setup

**1. Install the Chrome extension**

The extension is bundled with the MCP server. To get the path:

```bash
npx @shiplightai/mcp --chrome-extension-path
```

Then load it in Chrome:

- Open `chrome://extensions`
- Enable **Developer mode** (toggle in top right)
- Click **Load unpacked** and select the path from above

**2. Enable the relay server**

Add `SHIPLIGHT_RELAY_PORT` to your project's `.env`:

```
SHIPLIGHT_RELAY_PORT=15170
```

Reconnect the MCP server (e.g. `/mcp` in Claude Code) — the relay server starts automatically on the specified port.

**3. Configure the extension**

- Right-click the Shiplight extension icon → **Options**
- Set **Relay Server Port** to `15170` (must match your `.env`)
- Click **Save Settings**

**4. Attach a tab**

Navigate to the page you want to control, then click the Shiplight extension icon. The badge shows **ON** (orange) when the tab is attached and connected.

Badge indicators:

- **ON** (orange) — tab attached and connected
- **…** (yellow) — reconnecting
- **!** (red) — error, check extension options

## Option 2: Direct CDP Connection

You can also connect directly via the Chrome DevTools Protocol without the extension. Start Chrome with `--remote-debugging-port=9222`, then:

```
Attach to my browser at ws://localhost:9222/devtools/browser/...
```

This is more manual than the extension relay (you have to pass an explicit WebSocket URL) but it doesn't require installing anything.