DOMShell is a Chrome extension that maps the browser as a virtual file system. Windows and tabs become top-level directories (~). Each tab's accessibility tree becomes a nested file system, in which container elements are directories, and buttons, links, and inputs are files. Users can browse web pages through a terminal in the Chrome side panel using standard Linux commands (ls, cd, cat, grep, click, etc.).
Purpose
DOMShell is designed to let AI agents and humans browse and operate web pages in a familiar file system way. Traditionally, AI agents interacting with websites rely on screenshots, pixel coordinates, or fragile CSS selectors, whereas DOMShell exposes the browser's own accessibility tree, providing a deterministic, semantic file system abstraction applicable to any website, without the need for website-specific adapters.
Main Capabilities
Agents can: use ls ~/tabs/ to browse tabs, and use cd ~/tabs/123 to switch tabs; use ls and tree to explore pages without parsing screenshots; use cd navigation/ to navigate to sections without guessing coordinates; use click submit_btn to operate elements without fragile DOM queries; use cat to read content or use text for batch extraction without scraping innerHTML; use find --type combobox to search for elements without writing selectors.
DOMShell automatically detects page changes (navigation, DOM mutations, content updates caused by clicks), without the need for manual refresh. It supports command chaining (Bash-style composition), pipe operators (|) to filter output, path resolution supporting relative paths, and sibling navigation (--after and --before flags). The Tab key autocompletes commands and element names, and supports pasting multiline text.
Usage
Installation methods: can be installed from the Chrome Web Store (recommended, no build step required), or loaded into Chrome: open chrome://extensions/, enable Developer mode, click Load unpacked, select the dist/ folder, and click the DOMShell icon in the toolbar to open the side panel.
Open any web page, then open the DOMShell side panel to see the terminal. Starting from ~ (the browser root), you can use here to jump to the current active tab, or use ls to explore.
StandardGrouping (isolation): By default, it operates the entire browser in shared mode. The group command can place a session into an independent Chrome tab group, so that the agent works in a clearly marked channel while the user can browse freely in other tabs. Subcommands: group (status), group new [name], group attach <id>, group detach, group close, group list.
Multi-session: Each DOMShell client gets its own session channel—each sidebar window and each MCP connection is isolated. You can view all active channels with group list, and close a specified channel with group close <id>.
MCP client connection: DOMShell includes a hardened MCP server that allows any MCP-compatible client to control the browser through DOMShell commands. The server runs as a standalone HTTP service and can connect multiple clients simultaneously. Three installation paths are supported, with path 1 (recommended by default) installing via npm or running directly. The quick setup wizard can detect installed MCP clients (Claude Desktop, Cursor, Windsurf), generate a shared token, and write it into each client's configuration. The server starts two listeners: an HTTP port (default 3001) for MCP clients, and a WebSocket port (default 9876) for the Chrome extension bridge.
Connecting the extension: Enable the MCP Bridge switch on the extension options page, paste the token, and after saving, the status indicator turns green to indicate it is connected. You can also connect from the DOMShell terminal.
Security: The MCP server is read-only by default; Claude can browse but cannot click or type. Security levels include --allow-write, --allow-sensitive, and --domains restrictions. The token is stored via chrome.storage.local, and WebSocket connections with invalid tokens are rejected. All commands are logged to audit.log with timestamps.
domshell_execute interface: By default, a single tool, domshell_execute, is exposed, passing a command string and supporting multi-command calls (newline-separated, run in order, with output merged and returned). Use --granular to enable per-command tools; security is the same as in default mode.## Applicable scenarios
Suitable for scenarios that require AI agents to automate web page operations, such as browsing tabs, exploring page structure, navigating sections, clicking elements, reading content, searching for elements, etc. It is also suitable for human users who want to browse web pages in a command-line way.
Limitations
The material does not provide specific pricing, charging models, platform compatibility details (other than Chrome), performance data, or effect promises. Using MCP features requires additional configuration of the server and client.
