apireno/DOMShell

**The browser is your filesystem.** A Chrome Extension that lets AI agents (and humans) browse the web using standard Linux commands — ls, cd, cat, grep, click — via a terminal in the Chrome Side Panel.
Install from Chrome Web Store | npm package | Read the blog post | Project home
DOMShell maps the browser into a virtual filesystem. Windows and tabs become top-level directories (~). Each tab's Accessibility Tree becomes a nested filesystem where container elements are directories and buttons, links, and inputs are files. Navigate Chrome the same way you'd navigate /usr/local/bin.
Why
AI agents that interact with websites typically rely on screenshots, pixel coordinates, or brittle CSS selectors. DOMShell takes a different approach: it exposes the browser's own Accessibility Tree as a familiar filesystem metaphor.
This means an agent can:
- **Browse** tabs with ls ~/tabs/ and switch with cd ~/tabs/123 instead of guessing which tab is active
- **Explore** a page with ls and tree instead of parsing screenshots
- **Navigate** into sections with cd navigation/ instead of guessing coordinates
- **Act** on elements with click submit_btn instead of fragile DOM queries
- **Read** content with cat or bulk-extract with text instead of scraping innerHTML
- **Search** for elements with find --type combobox instead of writing selectors
The filesystem abstraction is deterministic, semantic, and works on any website — no site-specific adapters needed.
Installation
Chrome Web Store (Recommended)
Install DOMShell directly from the Chrome Web Store. No build step required.
From Source
Load into Chrome
1. Open chrome://extensions/
2. Enable **Developer mode** (toggle in top right)
3. Click **Load unpacked**
4. Select the dist/ folder
5. Click the DOMShell icon in your toolbar — the side panel opens
Usage
Getting Started
Open any webpage, then open the DOMShell side panel. You'll see a terminal:
You start at ~ (the browser root). Jump straight to the active tab with here, or explore:
Browsing Tabs and Windows
You can also navigate or open new tabs:
Tab Groups (isolation)
By default DOMShell operates on your general browser — **shared mode**, exactly as before. The group command puts a session in its own **isolated Chrome tab group**, so the agent works in a clearly-marked lane while you keep browsing freely in other tabs:
Subcommands: group (status), group new [name], group attach , group detach, group close, group list. Isolated mode keeps the agent out of your other tabs; shared mode is the default and unchanged.
When an MCP client connects, DOMShell automatically gives that session its own fresh 🐚 agent group. The group is **left open** when the session disconnects (non-destructive) — the agent is instructed to ask whether you'd like it closed before it wraps up, and you can always clear leftovers yourself with group close.
**Multi-session.** Every DOMShell client gets its own session lane — each side-panel window, each MCP connection, separately isolated. Two side panels in two Chrome windows hold independent positions; multiple concurrent MCP agents each work in their own 🐚 agent group with their own cursor. Run group list anytime to see every active lane; group close to close one.
**Multiple agents on one MCP connection.** Some MCP clients (e.g. Claude Desktop) share one connection across every chat — so by default two chats in the same client would land in one lane. Each chat can carve out its own lane by passing the group_id parameter to domshell_execute: pass "new" to create a fresh one (its id is returned at the end of the reply as [lane: ]), then pass that id on every later call. Two chats → two lanes → no collision. Agents can also use this for **handoff** — one agent reports its lane id, the next agent passes it as group_id and continues in the same state. Agents are instructed to close any lane they created when the task is done.
Navigating the DOM
Once you're inside a tab, the Accessibility Tree appears as a filesystem:
Type Prefixes
Every node has a type prefix that communicates metadata without relying on color alone:
| Prefix | Meaning | Examples |
|--------|---------|---------|
| [d] | Directory (container, cd-able) | navigation/, form/, main/ |
| [x] | Interactive (clickable/focusable) | buttons, links, inputs, checkboxes |
| [-] | Static (read-only) | headings, images, text |
Reading Content
Searching
Command Chaining (Bash-Style Composition)
DOMShell works like a filesystem — use the same mental model as searching files on disk. grep discovers where content lives (like grep -r in bash), cd scopes your context, and text/cat/find reads content (like cat/head/less). The pipe operator (|) filters output, just like bash.