dsh-browser-companion

<p align="center">

<strong>English</strong> | <a href="README.zh-CN.md">简体中文</a>

</p>

<p align="center"> <img src="assets/icon.png" alt="dsh-browser-companion" width="120" height="120"> </p>

A personal DeepSeek Harness (DSH) browser plugin.

It gives your agent a dedicated, persistent, visible browser:

• You can watch what the agent is doing in a real browser window.
• Logins are done by you in the popup window; passwords and OAuth secrets never pass through the agent.
• Cookies and login state are saved in the same profile, so logins persist across restarts.

Features

• ✅ Persistent browser profile (cookies / localStorage / login state)
• ✅ Visible window mode (default headless: false)
• ✅ Human-in-the-loop login: browser_login opens a window and you type your password / complete OAuth yourself
• ✅ Agent tools: open, snapshot, click, type, press, screenshot, see, select, check, upload, hover, scroll, tabs, status
• ✅ Security guard: browser_type refuses to fill password fields
• ✅ browser_see uses a local vision model (OpenAI-compatible) so the agent can understand images / visual layouts when needed
• ✅ Based on agent-browser, so the hard browser automation is battle-tested

Out-of-the-box

The plugin works with zero configuration for basic browsing:

• Uses the bundled browser (agent-browser's Chromium) by default
• Uses a default persistent profile under ~/.dsh/browser-profile
• All basic tools work: open, snapshot, click, type, tabs, etc.

Optional settings can be changed in the DSH WebUI plugin settings:

• executablePath: set to your real Chrome/Edge to avoid login blocks (e.g. Google)
• visionBaseUrl / visionModel: enable browser_see with a local vision model
• profilePath: use a custom browser profile location

If browser_see is not configured, it returns a friendly message instead of breaking the agent.

Install

1. Install dependencies

npm install -g agent-browser
agent-browser install   # first-time Chromium download

2. Install the plugin

From npm or GitHub (once published):

dsh plugin --profile web add dsh-browser-companion

> pnpm users: when installing from GitHub, pnpm may block agent-browser's build script. > Add this to your profile's pnpm-workspace.yaml and re-run: > ``yaml > allowBuilds: > agent-browser: true > ``

Or for local development, add this to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-browser-companion
      name: 'file:///absolute/path/to/dsh-browser-companion/src/index.js'
      config:
        profilePath: '/home/your-name/.dsh/browser-profile'
        headless: false
        executablePath: '/path/to/your/chrome'
        browserArgs: '--disable-blink-features=AutomationControlled'
        defaultTimeout: 30000

See [examples/dsh-browser-companion.config.yml](examples/dsh-browser-companion.config.yml) for a full sample config with placeholders.

> ⚠️ Never commit real paths, tokens, or personal profile data. Use the sample config and replace values locally.

3. Restart DSH

dsh web

Agent Tools

Typical Login Flow

Agent: I need to log in to a site.
Agent calls browser_login("https://example.com/login")
→ You see a popup and log in manually
→ You tell the agent "done"
→ Agent continues with the same cookies

How the Agent “Sees” a Page

• Default: browser_snapshot — fast, free accessibility tree with refs.
• Only when needed: browser_see — screenshot + local vision model, for images / visual layout / complex UI.

Configuration

Security Notes

• The agent is instructed never to fill password fields.
• Passwords and OAuth secrets are entered by the user in the visible browser window.
• For stronger protection, future versions can add encrypted cookie storage and proxy-based credential injection.

Development

npm install
npm test

License

MIT