dsh-browser

Usage

Three steps, and the agent needs no instruction beyond what it is asked to do:

1. Nothing, usually. The first tool call that needs a browser starts one, and the right sidebar opens itself on that session's Browser tab — you watch the page from its first frame. You can also open it by hand: New tab → Browser.
2. Ask for something. "Open the docs and tell me what the install section says" is enough: the tools act on the same browser the pane shows, so you watch the work happen.
3. Attach your own tools when you want them. curl http://127.0.0.1:9333/json/version answers while the browser runs; chrome://inspect, another Playwright over chromium.connectOverCDP, and scripts/cdp.mjs all attach to it.

Under the hood, the pane is a viewer of a browser that outlives it. Closing the tab does not stop the browser — reopen it and the same pages are there. The pane's own Close browser does both: the browser stops and the tab goes with it, because a viewer left behind is one more thing that could start a browser you asked to stop. Either way the next tool call that needs a browser starts a fresh one and the sidebar comes back for it. A browser is not a per-request resource: it stays alive between tool calls, which is what makes a conversation feel like it has a browser rather than a sequence of page loads.

---

Configuration

The settings section (Settings → Browser) edits the fields below and reports what is actually running, which is not the same thing as what is configured: the banner lists every session's browser with the port, window mode, and page count it really has. A deployment without a settings provider registers nothing, and the composition entry is the whole configuration.

Field	Default	Meaning
channel	chrome	Which installed browser to drive: chrome or msedge.
executablePath	empty	Explicit browser binary, for installs the channel lookup misses; overrides channel.
headless	true	Run without a window. Headless has nothing to occlude or minimize, so it is the recommended value.
stealth	true	Remove the two markers a Playwright-started browser carries: navigator.webdriver and, headless, a user agent spelled HeadlessChrome/….
userDataDir	empty	Parent directory of the per-session profiles; empty means a temporary profile per browser, removed when it exits.
debugPortMin / debugPortMax	9333 / 9400	Window the per-session CDP ports are allocated from; each browser takes the lowest free one. Changing it moves where the next browser listens and leaves running browsers on the ports they already hold.
viewportWidth / viewportHeight	1440 / 900	Page size in headless mode, which has no window to take a size from.
quality	70	JPEG quality of mirrored frames.
maxWidth / maxHeight	1600 / 1200	Longest edge of a mirrored frame, in device pixels.
everyNthFrame	1	Mirror every Nth composited frame.
snapshotNodes	300	Most accessibility-tree nodes one browser_snapshot prints before it truncates and says so.
maxInstances	4	How many session browsers may run at once; reaching the limit fails the request rather than evicting a browser someone is watching.
startupUrl	about:blank	First address a browser opens.
extraArgs	[]	Additional browser arguments, appended after the plugin's own.

stealth is on by default because it was measured, not assumed: with the markers in place Google served its "unusual traffic" page three times out of three, and with them removed three times out of three searches returned results — including for a real Edge window started the same way, which is what showed the markers rather than the browser to be the deciding factor. The setting exists so the comparison can be reproduced. When a deployment needs more than markers can hide, executablePath accepts any Chromium binary the user supplies, including hardened builds; no third-party binary is bundled or downloaded by this plugin.

---