# Reported issues for DOMShell

Pod holds 17 of 21 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [DOMShell](/mcp/domshell).

## Most discussed

### Playwright/Puppeteer backend

Alternative to the Chrome extension for headless agent workflows.

Use Playwright or Puppeteer as the browser automation backend instead of the Chrome debugger API.

From roadmap: **Platform**

[Read the thread](https://github.com/apireno/DOMShell/issues/25) · 2026-02-08 · open · 6 comments

### MCP server: confirmAction can deadlock the Node event loop in non-TTY parents

## Symptom

When the MCP server is launched without \`--no-confirm\` from a non-interactive parent (Claude Desktop, Cursor, any GUI MCP client), a \`tier === "write"\` command can deadlock the entire Node.js event loop instead of producing a clear deny.

## Root cause

\`confirmAction\` ([mcp-server/index.ts:85](mcp-server/index.ts#L85)) attempts to read user input via:

\`\`\`typescript
const fd = openSync("/dev/tty", "r+");
writeSync(fd, prompt);
const bytesRead = readSync(fd, buf, 0, 10, null

[Read the thread](https://github.com/apireno/DOMShell/issues/39) · 2026-05-26 · closed · 3 comments

### feat(extension): honor `initial_url` for group_id="new" — eliminate about:blank placeholder on lane creation

## Goal

Eliminate the `about:blank` placeholder tab that gets created on `group_id="new"` lane creation when the agent already knows the URL it wants to start at. Make the fresh lane's working tab navigate directly to the target URL.

## Background

Today, `group_id="new"` triggers `createAgentLane()` → `groupNew(["agent"])` which calls `chrome.tabs.create({ url: "about:blank", active: false })` to get a tab Chrome will let us group. Then the agent's first `open <url>` call creates a *second* t

[Read the thread](https://github.com/apireno/DOMShell/issues/52) · 2026-06-17 · closed · 2 comments

### feat(extension): drop eager groupNew on SESSION_START — connection-default lane should only exist if explicitly requested via group_id="new"

## Goal

Stop the eager `groupNew(["agent"])` call in the WS bridge's `SESSION_START` handler. The connection-default lane (the Chrome tab group with one `about:blank` tab, titled `🐚 agent`) that's currently auto-created on every MCP `initialize` should not exist. Isolation should happen **only** when the agent explicitly requests it via `group_id="new"`.

## Why this is the right fix

A QA-UX integrator team reported that orphan `agent` tab groups accumulate across connection cycles — unattribu

[Read the thread](https://github.com/apireno/DOMShell/issues/53) · 2026-06-20 · closed · 1 comment

### createAgentLane silently swallows groupNew failure — group_id="new" can return no [lane:] marker with no error

## Symptom

`domshell_execute` with `group_id="new"` sometimes returns a successful command result with **no `[lane: ...]` marker and no error**. The agent has no signal that their requested isolated lane was never created — they just see the command output and have no handle to rejoin.

Observed during 2.0.2 validation cycle (cowork agent and Claude Desktop, multiple times).

## Root cause

[src/background/index.ts:192](https://github.com/apireno/DOMShell/blob/main/src/background/index.ts#L192)

[Read the thread](https://github.com/apireno/DOMShell/issues/48) · 2026-06-01 · closed · 1 comment

### Stdio MCP disconnect leaves auto-assigned lanes orphaned

## Symptom

In stdio MCP mode, every connection auto-creates a lane (\`mcp:<sid>\`) on \`SESSION_START\`. When the client disconnects, the lane stays around — by design — so HTTP MCP clients can reconnect with the same session id and rejoin their lane.

For **stdio MCP, every connection is genuinely fresh** — there's no reconnect case. A wrapper that opens a fresh \`ClientSession\` for each call (the canonical pattern when the agent doesn't want long-lived MCP state, e.g., HKUDS/CLI-Anything's n

[Read the thread](https://github.com/apireno/DOMShell/issues/47) · 2026-05-29 · closed · 1 comment

### Document continue-on-error semantics of multi-line domshell_execute

## What needs documenting

[\`mcp-server/index.ts:1115-1127\`](https://github.com/apireno/DOMShell/blob/main/mcp-server/index.ts#L1115-L1127) — when \`domshell_execute\` receives multi-line input, the splitter runs each line in sequence and **does not halt on error**:

\`\`\`typescript
for (const line of lines) {
  if (lines.length > 1) out.push(\`$ \${line}\`);
  const r = await execWithSecurity(line, sidRef.sid, lane);
  out.push(r.result);
  laneId = r.laneId;
  if (lane === \"new\" && r.lane

[Read the thread](https://github.com/apireno/DOMShell/issues/46) · 2026-05-27 · closed · 1 comment

### js / eval can hang the MCP call when the expression returns a non-resolving Promise

## Symptom

\`js <code>\` and \`eval <code>\` (same kernel function under the hood) can hang indefinitely if the user's expression returns a Promise that never resolves — or if the expression triggers a page-level deadlock (broken navigation, beforeunload that waits on something, infinite loop in a handler).

The MCP-side call sees a timeout. The CDP target stays stuck. Worst case the agent gives up and the user sees a stalled tool call.

Surfaced 2026-05-25 by an agent dispatching mouse events 

[Read the thread](https://github.com/apireno/DOMShell/issues/38) · 2026-05-26 · closed · 1 comment

## Most recent

### bug(extension+mcp-server): WS bridge goes zombie after long idle; one-sided keepalive cannot detect it (timeouts -32001 until manual restart)

## Symptom

After DOMShell has been idle for hours/days (no MCP traffic, Claude Desktop wasn't actively driving the browser), the next `domshell_execute` call from a client hits an MCP `-32001 Request timed out`. The container is healthy, the WS socket on port 9876 still reads `ESTABLISHED` in netstat, the side panel says "connected (authenticated)" — but **commands sent over the WS never get a response.** Only fix observed: restart the thv proxy AND the Chrome extension (both — neither alone re

[Read the thread](https://github.com/apireno/DOMShell/issues/51) · 2026-06-12 · open · 0 comments

### AX-tree collapsing hides React-handler-bearing inner divs (LinkedIn-style fake links)

## Symptom

Some SPAs bind their React activation handlers to an **inner** \`<div tabindex="0">\` wrapper rather than to the semantic outer element. The AX tree treats those inner divs as collapsible noise (role=\"generic\" with no accessible name → \`shouldFlattenNode\` returns true in [vfs_mapper.ts:122](src/background/vfs_mapper.ts#L122-L133)), so they don't appear in the VFS as discrete nodes. DOMShell can \`focus\` and \`click\`/\`key\` the OUTER element, but the React handler — bound to th

[Read the thread](https://github.com/apireno/DOMShell/issues/45) · 2026-05-26 · open · 0 comments

### Agent-declared sessions — address a DOMShell lane by id, for multi-chat isolation and handoff

## Problem

DOMShell gives each MCP *connection* its own isolated session (#33). But MCP exposes no identity below the connection — clients like Claude Desktop multiplex every chat over a single connection, so two chats land in the same lane and share it.

## Proposed direction

Add an optional `group_id` parameter to `domshell_execute`:

- **omitted** → the connection's current lane (stable — never spawns a new one)
- **`"new"`** → create a fresh lane; the command runs in it; the new id is retu

[Read the thread](https://github.com/apireno/DOMShell/issues/34) · 2026-05-22 · open · 0 comments

### Session tab-group isolation — agent works in its own tab group while you browse

## Problem

When DOMShell drives the browser, there is no separation between the agent's tabs and the user's tabs — the agent attaches to a tab inside the user's normal Chrome window. You cannot tell which tabs the agent controls, and nothing stops it from navigating or acting on a tab you are actively using. Sharing one Chrome window between a human and an agent is error-prone.

## Proposal

When an MCP session starts, DOMShell creates a labeled Chrome tab group and places its working tab(s) in

[Read the thread](https://github.com/apireno/DOMShell/issues/32) · 2026-05-21 · open · 0 comments

### Experiment: DOMShell vs Raw HTML interface comparison

## Summary

Run an apples-to-apples comparison of DOMShell's AX-tree filesystem interface vs raw HTML scraping, using the **same model** (Qwen3-4B) on the **same tasks**.

## Design

**Core matrix — `[nexa, ollama] x [domshell, html]`:**

| | **DOMShell** | **Raw HTML** |
|---|---|---|
| **Nexa serve** | agent.py via MCP | raw_html_agent.py via requests+BS4 |
| **Ollama** | agent.py via MCP | raw_html_agent.py via requests+BS4 |

All 4 cells use the same Qwen3-4B weights. Only variables: interfa

[Read the thread](https://github.com/apireno/DOMShell/issues/29) · 2026-02-10 · open · 0 comments

### Experiment: DOMShell vs Vision (browser-use) with same local model

## Summary

Run the same Wikipedia tasks from `experiments/nexa/` using Nexa's vision-based [Web-Agent-Qwen3VL](https://github.com/NexaAI/nexa-sdk/tree/main/cookbook/PC/Web-Agent-Qwen3VL) (Playwright + screenshots) and compare against the DOMShell results.

## Why

The current Nexa experiment compares 1.7B/4B local models against Claude Opus — that's a model-size comparison, not an interface comparison. To validate DOMShell's text/AX-tree design, we need an apples-to-apples test: **same model, s

[Read the thread](https://github.com/apireno/DOMShell/issues/28) · 2026-02-10 · open · 0 comments

### --text flag: inline visible text previews for ls and find

## Summary

Add a `--text` flag to `ls` and `find` that shows inline visible text previews per element using `.innerText` (rendered text only, respects CSS `display:none` and `visibility:hidden`).

## Problem

When agents scan a page, they must `cat` each element individually to see what text it contains. For a page with 50 links, that's 50 tool calls just to read link labels.

## Solution

### `ls --text` and `find --text`
Shows a truncated, dimmed text preview inline with each element:
```
[x]

[Read the thread](https://github.com/apireno/DOMShell/issues/27) · 2026-02-08 · open · 0 comments

### Switch MCP server from stdio to SSE/Streamable HTTP transport

## Problem

The current MCP server uses stdio transport, meaning it must be spawned as a child process by a single MCP client (e.g. Claude Desktop). This means:
- Only one client can use it at a time (Claude Desktop OR Claude CLI, not both)
- Server lifecycle is tied to whichever client spawned it
- Each client needs its own config entry

## Solution

Switch to SSE (Server-Sent Events) or Streamable HTTP transport:
- MCP server runs as a standalone long-lived HTTP server on `localhost:9876/mcp`

[Read the thread](https://github.com/apireno/DOMShell/issues/26) · 2026-02-08 · open · 0 comments

### Standalone headless browser mode

Ship DOMShell as a self-contained headless Chromium process (via Chrome for Testing or embedded Chromium) that agents launch directly.

- No extension install, no user Chrome profile
- `npx domshell --headless` and connect via MCP
- Ideal for CI pipelines, server-side automation, and agent-in-a-loop workflows

From roadmap: **Platform**

[Read the thread](https://github.com/apireno/DOMShell/issues/23) · 2026-02-08 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/apireno/DOMShell/issues).