Embedded Browser

The embedded browser pane lets you point an isolated Chromium webview at any URL inside the task detail dialog, then capture the rendered frame plus annotations and submit it to the active agent as a multi-modal prompt. Useful for visual regression work, “make this match the design” loops, and DOM-level bug hunting where a screenshot beats a paragraph of description.

Opening the Browser Pane

1. Open a task with an active agent session.
2. Click the Browser pill in the task detail dialog header (mutually exclusive with Changes).
3. The first time you open it for a task, an empty-state prompt asks for a URL. Pick a quick-pick (localhost:3000, 5173, 4321, 8080) or type one.

The URL bar supports back, forward, reload, pin to project default, and pin to task override. Per-task URLs persist in .kangentic/browser-urls.json. The project default lives in AppConfig.browser.defaultUrl. Resolution rule: task override > project default > empty state.

Every successful navigation quietly updates that task’s own URL, so reopening a task lands you where you left it. The project default is never set automatically. It changes only when you ask for it, through Save as project default in the pane or Settings > Browser > Default URL. Before v0.36.0 the first navigation in a fresh project seeded the project default, which meant every sibling task inherited that one task’s URL. Now that tasks lease their own dev-server ports, inheriting another task’s URL is a collision rather than a convenience.

Note

A task’s reserved dev-server port deliberately does not auto-navigate its pane. Kangentic reserving a port is not evidence that anything is serving on it, so opening onto one would show a blank page for a server that was never started there. The empty state at least tells you what to do next.

Since v0.30.0 the Browser pane is also a detachable surface: a pop-out button moves it into its own OS-level window (one per task), which remembers its size, position, and monitor between openings. The same engine detaches the Changes panel, a single file’s diff, the Usage Stats Dashboard, and the Agent Monitor.

Hiding Is Not Closing

The pane has two verbs, and the difference is what happens to the page.

The Browser pill only hides. The page stays loaded, so you get it back exactly as you left it - scroll position, form state, and whatever the app kept in memory - and an agent driving the pane is never interrupted by you reclaiming the space. Opening the Changes panel over it, and closing the task’s window while its agent is still running, both keep it the same way.

Close browser is the discard. It ends the page and frees its renderer process, which is real memory: a loaded page costs roughly 120 MB, more for a heavy app. Reach it in two places:

• the red-tinted Close browser button at the far left of the pane’s navigation bar, ahead of Back
• the Close browser item in the task menu, which is how you close a pane you cannot see because it is hidden

Either way, the task’s URL is remembered, so Show reopens the same address on a fresh page. What does not survive is per-page state: anything the site kept in sessionStorage or in memory is gone, the way it would be if you had closed a browser tab. Cookies and localStorage persist in the task’s cookie jar.

Two indicators say a page is loaded and costing memory, in any state - showing, hidden, or with its window closed:

• a green dot on the Browser pill in the task detail header
• a green globe at the right end of the task card’s title row on the board

Neither says whether an agent is driving the page right now; that is the pane’s own accent border and “Agent typing here” marker.

Note

Closing the pane’s pop-out window is not Close browser either: the pane reclaims its place inline. That is the deliberate difference from the Changes panel, whose pop-out closing leaves the panel closed. Close browser is not offered inside a pop-out window at all - closing the window is what ends that page.

Modes

Draw

Press Ctrl+D / Cmd+D to enable Draw mode. Free-draw strokes appear on a transparent overlay above the webview. Pointer events route to the canvas while drawing so the page below doesn’t intercept them.

Inspect

Press Ctrl+I / Cmd+I to enter Inspect mode - a red highlight tracks the element under your cursor. Click an element to capture a structured fingerprint: selector, ARIA role, ARIA name, data-testid, classes, ancestor chain, computed styles, and outerHTML. The picked element then keeps a persistent blue overlay that follows scroll and resize until you re-enter Inspect or press Escape.

Zoom

The browser pane has Chrome-style zoom controls. Three ways to use them:

• Toolbar pill - the URL bar has a - / % / + group next to the Pin button. Click - or + to step zoom; the middle pill shows the current percentage.
• Keyboard - Ctrl+= / Cmd+= to zoom in (the plus key works too), Ctrl+- / Cmd+- to zoom out, Ctrl+0 / Cmd+0 to reset to 100%. Shortcuts are gated on the browser pane being hovered or focused, so they don’t fight other dialogs.
• Ctrl+Wheel - scroll the wheel with Ctrl held inside the webview (Ctrl on every platform). Handled in the main process via webContents zoom-changed, with a broadcast back to the toolbar so the percentage pill stays in sync.

Zoom snaps to a fixed ladder from 25% to 500% (matching Chrome’s rungs). The ladder is shared between main and renderer in src/shared/zoom-steps.ts.

Sending to the Agent

Press Ctrl+Enter / Cmd+Enter to submit. Kangentic:

1. Composites the webview frame and your strokes into a single PNG written to <projectRoot>/.kangentic/sessions/<sessionId>/captures/capture-<timestamp>.png.
2. Builds an XML-tagged prompt: a top-level Screenshot: @<path> for bare-token @-parsers (Claude Code, Gemini CLI), then a <browser_context> envelope with <url>, optional <picked_element>, and any selected text.
3. Submits via the paste engine to the active agent’s PTY.

Captures live under the session directory, so they’re cleaned up automatically when the task moves to To Do, Done, or is deleted.

Agent-Driven Automation

The pane works in the other direction too: agents can drive it themselves. Every spawned session gets the kangentic_browser_* MCP tools (open and close panes, list panes, navigate, screenshot, query the DOM, click, type, press keys, drag, wait, read the console, eval), which control the pane over the Chrome DevTools Protocol. An agent can open its own task’s pane rather than asking you to click the Browser pill, and put it away again when it is done. That closes the loop on frontend work without leaving the task: the agent edits code, points the pane at your dev server, and looks at the rendered result - or clicks through the flow it just built to verify it.

An agent targets a surface by handle (sessionId) or by taskId, or omits both, in which case it gets only its own task’s surface. Since v0.38.0 that implicit resolution never falls through to a sibling task’s pane, however many are open in the project: the fall-through was observed navigating another task’s signed-in app to an identity-provider URL, and an agent reaching a page it was never pointed at is a worse outcome than a refusal it can read. Only a caller with no task at all - a human-driven client, or the Command Terminal - uses the project-wide rule. Panes are scoped to the agent’s own project: the family takes no project selector at all, so there is no path to another project’s pane.

The whole family is gated by the Agent Browser settings tab, a per-machine security policy: a master switch (off unregisters the tools entirely), plus sub-gates for interaction (click/type/keypress/drag - off means observe-only), navigation, arbitrary JavaScript eval (off by default), and restricting navigation to localhost.

An agent can also see, but not change, whether you can watch it work: every surface reports a visibility of showing, hidden, parked, or offscreen. All four are driveable - the field says whether the page is on your screen, not whether the agent may act on it.

See the MCP Server reference for every tool, Settings for the toggles, and the Configuration Reference for the browserAutomation.* keys.

Browser Lanes, for Concurrent Agents

Added in v0.36.0. Several agents working under one task used to resolve to that task’s single pane and drive it at once, interleaving navigations, clicks, and screenshots while each believed it had exclusive control. Two mechanisms fix that.

Drives are serialized per pane. Only one caller drives a given browser at a time, and the rest queue. A drive that cannot get its turn within 30 seconds refuses with an actionable error rather than hanging, and every drive records who made it, so contention is visible instead of mysterious.

Each agent can take a lane of its own. Calling kangentic_browser_open_pane with isolated: true returns a private browser lane and a laneId to pass as sessionId on later calls. Serializing commands stops them interleaving, but it cannot stop one agent navigating away from the page another is midway through verifying. Only separate surfaces do that.

A lane renders offscreen. It never appears in the task detail window, never disturbs the pane you are looking at, and cannot take your keyboard focus. It shares the task’s own cookie jar, so an agent in a lane inherits logins you already have rather than landing on a sign-in wall. Lanes are created on demand, run at a throttled frame rate so an animating page nobody is watching does not burn CPU, and are destroyed as soon as they are not needed: when their session exits, when the project is torn down, and when they go idle. A lane in use is never reclaimed.

The browser survives the window closing

A browser an agent is using belongs to the agent, not to a piece of UI. Closing a task’s detail window used to destroy its browser guest outright, leaving the agent with no pane and no way to reopen one.

Since v0.38.0 that close parks the window instead: when the task has a loaded page and a running agent, closing hides the window in place rather than tearing it down. Reopen the task and it un-parks - the same page, the same tab, nothing reloaded, per-page state intact. The park ends on its own once there is nothing left to keep: the agent’s session stops, or the page goes away. The same holds while a project is backgrounded, so an agent can keep driving its pane, and can open a lane, without its project being the one on screen.

When a page genuinely does go away - a hard reload, the pane detaching into a pop-out, a window that could not be kept - and the task still has a live agent session, Kangentic hands the page off to an offscreen lane at the same URL under the same task. The agent that made no assumption about which surface it was on keeps working; one holding the old surface’s handle is told plainly that its tab is gone and which surface replaced it, rather than being silently pointed at a different page. Reopen that task’s Browser pane and the hand-off lane stands down, because the visible pane is the better answer whenever it exists. A lane the agent asked for with isolated: true is its own working surface and is never taken away this way.

Close browser stands up no lane. You closed the page to get its memory back, so nothing re-spends it behind you; the agent’s next call is told the user closed the browser, and it may open a new one.

While an agent drives the pane you are watching

An agent clicking in the pane makes the browser take focus, which would otherwise blur whatever you were typing into mid-sentence. Since v0.36.0 the pane knows exactly when a drive is happening and gives your focus back when it ends.

If you type into the pane while an agent is driving it, your keystrokes are intercepted before the page sees them and routed to the terminal you were typing in, so your sentence continues where you meant it rather than landing in a web form.

Mouse back and forward also work over a loaded page now. A page consumes the mouse outright, so those presses were previously invisible to Kangentic: a tap navigates back, and a hold still triggers push-to-talk dictation.

A build error is reported, not screenshotted

When a screenshot would capture a dev-server build-error overlay, Kangentic returns the error text instead of the picture. Handing an agent a JPEG of a red rectangle is technically correct and practically useless: it spends a turn working out what it is looking at, and when several agents share one dev server the one that sees the overlay is usually not the one who broke the build.

Sign-in Pop-ups

Also new in v0.36.0. The pane used to deny every window.open, which made any site whose sign-in is a pop-up present as a dead button with nothing to explain it. http(s) pop-ups are now allowed, on terms that keep the surface the old refusal was protecting closed:

• The pop-up window is chromed, and Kangentic owns its title, forcing it to the live origin (an http origin is labeled not secure). The OS title bar is the only origin indicator such a window has, and a page free to name itself is exactly the phishing affordance to avoid.
• Its security preferences restate the guest’s hardening in full: no Node integration, context isolation on, sandboxed, web security on.
• It shares the guest’s session, so an OAuth cookie lands in the same per-task jar, and window.opener and postMessage keep working, which nearly every OAuth flow depends on.
• The page’s requested size is honored within limits; its requested position is ignored and the window is centered on its parent.
• A pop-up may open one more pop-up under the identical policy, so a chained identity-provider hop stays in one cookie jar. A pane is capped at four live pop-ups, and they close with the pane that opened them.

Some identity providers refuse OAuth from an embedded browser on principle. The refusal is specific to the pop-up path: a third-party site’s “Sign in with Google” button opens an OAuth window that Google answers with disallowed_useragent. Signing in first-party, by pointing the pane at accounts.google.com itself, completes and leaves you with a real authenticated session - which is what the shared login below carries between tasks. When Kangentic recognizes the OAuth bounce it offers to open that sign-in in your own browser instead. Kangentic does not spoof its user agent to get around the block: it is a deliberate anti-phishing control, and defeating it would misrepresent Kangentic to every site the pane visits.

Signing in Once per Project

Per-task cookie jars solve one problem and used to create another. Isolating localhost also isolated everything else, so you re-entered your Google, GitHub, or SSO login once per task, for an account the browser next door was already signed into. Since v0.37.0 the split runs by cookie domain instead of by task.

Identity-provider logins are shared across a project. Non-localhost cookies live in a per-project identity jar. A task’s pane syncs from that jar when it opens, and a sign-in in one task mirrors back out to it, so the next task starts signed in. The sharing survives restarts and reaches tasks you create later.

Dev-server logins stay isolated. localhost, 127.0.0.1, and [::1] cookies are never copied in either direction, so two tasks signed into different accounts on their own dev servers behave exactly as before.

Three limits are worth knowing before you lean on it:

• Sharing is add-only. Signing out in one task does not sign you out anywhere else. Clear Browser Data is the wipe-everywhere path, and it includes the identity jar.
• Two different accounts at the same provider, across tasks, at the same time is unsupported - not “last one wins”. A jar can end up holding a mixed set of both accounts’ cookies, which the provider may answer with a “verify it’s you” challenge. Clear Browser Data is the way out.
• A fresh task’s pane starts signed in. That is the feature, and it is also the cost: an agent driving a brand-new pane can act with your identity-provider session, the same trade browser lanes already make within a task. For a project where that is not a trade you want, turn the pane off with Browser Enabled.

Propagation happens when a pane opens rather than live, so two panes already open side by side will not see each other’s sign-in until one of them is reopened.

Downloads

A download started in the pane, by you or by an agent, saves to your OS Downloads folder, dedupes its filename rather than overwriting, shows progress on the host window’s taskbar, and raises a toast when it finishes. Nothing opens a modal save dialog, which would block a pane an agent is mid-way through driving.

Downloads are allowed rather than denied on purpose: the agent driving the pane already has full filesystem write through its own tools, so refusing would only break your use of the pane. The toast is what stops an agent-triggered download from being invisible.

Settings

Open Settings > Browser:

Setting	Default	Description
Browser Enabled	On	When off, the Browser pill is hidden in the task detail window header, and an agent trying to open a pane over MCP is refused rather than opening one you have no pill to close
Default URL	empty	Project-overridable fallback URL when a task has no per-task override
Clear Browser Data	(action)	Destructive button. Clears cookies, localStorage, IndexedDB, cache, and service workers from every browser partition for the project: each task’s own cookie jar, the project’s identity jar, and the legacy shared jar. Per-task and project URL overrides are intentionally left alone - those are workflow state, not browsing identity

Note

The Browser pane is isolated per task: each task gets its own persistent cookie jar (persist:kng-<projectId>-<taskId>), so two tasks running dev servers on the same localhost host don’t clobber each other’s logins. Since v0.37.0 the jar is keyed by the task’s identity rather than by its folder, so relocating a worktree, renaming it, or sending a task to Done and back no longer signs you out. Cookies persist across app restarts, and a task with no project falls back to a single shared jar (persist:kangentic-browser). Jars left behind by deleted tasks and projects are reclaimed on startup, and the old path-keyed jars are swept once in the same pass - so expect to sign in one more time after upgrading. Use Clear Browser Data when you need a clean slate.

Security

The webview runs in its own renderer process with nodeIntegration: false, contextIsolation: true, sandbox: true, and webSecurity: true. Non-http(s): URLs are rewritten to about:blank. http(s) pop-ups are allowed under the hardened policy described in Sign-in Pop-ups above; anything else is denied. The host renderer can only reach the webview through the inspector’s executeJavaScript and the navigation/capture APIs.

Cross-Platform Notes

Platform	Behavior
Windows	WSL-localhost is not reachable from the Windows host. The empty state surfaces a hint with the wsl hostname -I workaround
macOS	NativeImage capture includes the alpha channel; composited correctly into the PNG
All	Self-signed HTTPS dev servers show the standard Chromium interstitial - accept it once or use plain HTTP

See Also

• MCP Server - Browser Automation - the kangentic_browser_* tools agents use to drive the pane
• Configuration Reference - Browser settings
• Creating Tasks - task detail dialog basics