# dsh-plugin-browser

**English** | [中文](./README.md)

15 browser tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): the model in your session can drive a **logged-in real Chrome**. Whatever you are logged into there (GitHub, intranet portals, subscription sites), the model can access it — no re-entering passwords.

```
You:  check my GitHub notifications today
Model: browser_navigate → browser_snapshot → reads the list → reports back
```

## Tools (15)

| Tool | What it does |
|---|---|
| `browser_session` | Start/switch session (`real` logged-in Chrome \| `isolated` separate & clean) |
| `browser_navigate` | Open a URL |
| `browser_snapshot` | List interactive elements with `ref` ids (viewport-only by default, token-lean) |
| `browser_click` / `browser_type` / `browser_select_option` / `browser_hover` | click / type / select dropdown / hover, targeted by `ref` |
| `browser_tabs` | Tab management (list / switch / close / new) |
| `browser_handle_dialog` | Pre-set handling for JS dialogs (alert/confirm) |
| `browser_eval` | Run JS in the page (like the F12 console) |
| `browser_storage` / `browser_console` | Read cookies/localStorage / read console logs |
| `browser_wait_human` | On captchas/logins, **shows a card in DSH and waits for you to finish** (5 min timeout) |
| `browser_screenshot` | Save a screenshot to a file |
| `browser_close` | Close the session (`real` only drops the connection; your Chrome stays open) |

Chrome not running? The plugin launches it automatically.

## Install

> ⚠️ **Pick ONE of the two methods — mixing them creates a duplicate plugin row and breaks DSH startup.**

### Option A: DSH Desktop users

```bash
# 1. Clone and install
git clone https://github.com/q35888/dsh-plugin-browser.git \
  ~/.dsh/profiles/web/plugins/dsh-plugin-browser
cd ~/.dsh/profiles/web/plugins/dsh-plugin-browser && npm install --ignore-scripts
npx playwright install chromium   # only needed for isolated mode (~95MB); skip if you only use real mode

# 2. Package-name resolution link
ln -sfn ../web/plugins/dsh-plugin-browser ~/.dsh/profiles/node_modules/dsh-plugin-browser

# 3. Append to the machine-level config (applies to all profiles)
cat >> ~/.dsh/cordis.patch.yml <<'EOF'
- insert:
    - id: dsh-plugin-browser
      name: dsh-plugin-browser
EOF

# 4. Restart DSH Desktop
```

For a single profile only: write the row from step 3 into `~/.dsh/profiles/<name>/cordis.patch.yml` instead of the machine-level file.

### Option B: dsh CLI users

```bash
dsh plugin --profile web add github:q35888/dsh-plugin-browser
# then add "dsh-plugin-browser" to the dsh.profile.bundles array in
# ~/.dsh/profiles/web/package.json (a bundle patch ships with the package)
```

## Configuration (all optional)

| Env var | Default | Meaning |
|---|---|---|
| `AGENT_BROWSER_DIR` | `~/.pi/agent` | Root dir; the paths below derive from it |
| `AGENT_BROWSER_CHROME_STARTER` | `<root>/start-agent-chrome.sh` | Custom Chrome launcher script (used first if present; handy for proxies/special flags) |
| `AGENT_BROWSER_CDP_PROFILE` | `<root>/chrome-cdp-profile` | User-data dir of the logged-in Chrome — **your login state lives here** |
| `AGENT_BROWSER_ISOLATED_PROFILE` | `<root>/bw-mcp-profile` | Separate dir for `isolated` mode |
| `AGENT_BROWSER_CDP_PORT` | `9222` | CDP port |
| `AGENT_BROWSER_ISOLATED_CHANNEL` | unset | `chrome` makes isolated mode use the system Chrome instead of Playwright's bundled chromium. **Caution on macOS**: a headless system Chrome gets registered as "Chrome is running" and blocks your daily Chrome from launching via the Dock |
| `AGENT_BROWSER_NO_SANDBOX` | unset | `1` forces `--no-sandbox` (rarely needed) |

**About the default dir**: defaults exist so users of [agentic-browser-mcp](https://github.com/q35888/agentic-browser-mcp) (this plugin's predecessor) share the same logged-in Chrome seamlessly. If you don't care about that, set `AGENT_BROWSER_DIR` to your own location — the plugin creates it automatically.

**Bringing login state along**: on first `real`-mode use the plugin opens a dedicated Chrome window (fully separate from your daily browser). **Log in once** to the sites you need — the state persists in `AGENT_BROWSER_CDP_PROFILE` and is available every time after.

## Usage notes

- **refs are temporary**: each `snapshot` renumbers them; re-snapshot after the page changes
- **Captchas / 2FA**: the model calls `browser_wait_human`, a card appears in DSH, you finish in the browser and confirm
- **Tabs**: newly opened tabs are followed automatically; pin one with `browser_tabs` `switch`
- **Privacy note**: `browser_eval`/`browser_storage` can read cookies and login credentials from the browser — use this plugin only in sessions you trust

## Troubleshooting

- **Model reports Chrome connection failure** — self-healing is built in (the "zombie" state where all windows are closed but the process lives is recovered automatically); if it keeps failing, fully quit Chrome and let the model retry
- **Your own Chrome won't open from the Dock** (macOS) — older versions launched headless isolated sessions with the system Chrome, which macOS treats as "Chrome already running", blocking your daily Chrome; fixed (isolated now uses Playwright's bundled chromium, fully separate). Setting `AGENT_BROWSER_ISOLATED_CHANNEL=chrome` with headless mode brings this back
- **Auto-launch fails (Chrome not found)** — the plugin checks common install locations plus PATH; if all else fails, write a launcher script and point `AGENT_BROWSER_CHROME_STARTER` at it
- **Where are screenshots** — `<root>/bw-shots/`

## Known limitations

- Multiple sessions/subagents in one DSH process **share the same browser tab** and can interfere with each other when used concurrently (serial protection exists within a single session)
- If DSH exits unexpectedly during `isolated` mode, the separate browser process may linger — close it manually; `real` mode is unaffected
- Depends on DSH's rc-phase tooling API; if it breaks after a major DSH upgrade, removing the two machine-level config rows fully rolls back

## License

MIT