chromux

tmux for Chrome tabs — zero-dependency parallel Chrome tab controller via raw CDP.

Why

AI agents need to browse the web in parallel using the user's real Chrome (with logins preserved, no bot detection). Existing tools either bundle their own Chromium (Playwright/Puppeteer) or can't isolate tabs properly (agent-browser --cdp --session).

chromux solves this by talking to Chrome's DevTools Protocol directly using only Node.js built-ins — no Playwright, no Puppeteer, no npm dependencies.

| | Playwright/Puppeteer | agent-browser --cdp | chromux | |---|---|---|---| | Browser | Bundled Chromium | Real Chrome | Real Chrome | | Bot detection | Often caught | Avoided | Avoided | | Tab isolation | Yes | No (sessions share tab) | Yes | | Parallel agents | Yes | Broken | Yes | | Dependencies | 100s of MB | playwright-core | None | | Profile management | No | No | Yes |

Prerequisites

• Node.js >= 22 (for built-in WebSocket)
• Google Chrome installed

Quick Start

# Launch Chrome with an isolated profile (auto-finds Chrome, auto-assigns port)
chromux launch

# Open tabs for two agents
chromux open agent-a https://news.ycombinator.com
chromux open agent-b https://reddit.com/r/programming

# Each operates independently
chromux snapshot agent-a
chromux click agent-a @3
chromux eval agent-b "document.title"
chromux screenshot agent-a /tmp/hn.png

# Clean up
chromux close agent-a
chromux close agent-b
chromux kill default

Profile Management

Each profile is an isolated Chrome instance with its own user-data-dir, logins, cookies, and extensions.

# Launch named profiles
chromux launch work
chromux launch personal

# See what's running
chromux ps
# PROFILE             PORT    PID       STATUS      TABS
# work                9300    12345     running     3
# personal            9301    12346     running     1

# Use a specific profile for tab commands
chromux --profile work open my-tab https://...
CHROMUX_PROFILE=personal chromux open other-tab https://...

# Default profile is "default" — used when no --profile specified
chromux open my-tab https://...  # → uses "default" profile (auto-launches if needed)

# Stop a profile
chromux kill work

Commands

Profile

| Command | Description | |---------|-------------| | launch [name] | Launch Chrome with isolated profile (default: "default") | | launch <name> --port N | Launch with specific port | | ps | List running profiles | | kill <name> | Stop profile (Chrome + daemon) |

Tab Operations

| Command | Description | |---------|-------------| | open <session> <url> | Navigate (auto-creates tab) | | snapshot <session> | Accessibility tree with @ref numbers | | click <session> @<ref> | Click element by ref | | click <session> "selector" | Click by CSS selector | | fill <session> @<ref> "text" | Fill input field | | type <session> "text" | Keyboard input (Enter, Tab, etc.) | | eval <session> "js" | Run JavaScript expression | | screenshot <session> [path] | Take PNG screenshot | | scroll <session> up\|down | Scroll page | | wait <session> <ms> | Wait milliseconds | | close <session> | Close tab | | list | List active sessions in current profile | | stop | Stop daemon (keeps Chrome running) |

Architecture

~/.chromux/
  config.json                    Global config (optional)
  profiles/
    default/                     Chrome user-data-dir
      .state                     PID, port, socket path
    work/
      .state

Chrome instance A (port 9300, ~/.chromux/profiles/default/)
  ↑ CDP WebSocket per tab
chromux daemon (Unix socket /tmp/chromux-default.sock)
  ↑ HTTP
CLI / AI agents

Chrome instance B (port 9301, ~/.chromux/profiles/work/)
  ↑ CDP WebSocket per tab
chromux daemon (Unix socket /tmp/chromux-work.sock)
  ↑ HTTP
CLI / AI agents

• No Playwright/Puppeteer — raw WebSocket + http from Node.js stdlib
• Tab CRUD via Chrome's /json/* HTTP endpoints
• Page ops via CDP WebSocket JSON-RPC
• Daemon per profile keeps WebSocket connections alive across CLI invocations
• Auto-launch — chromux open auto-launches default profile if needed

Configuration

Optional ~/.chromux/config.json:

{
  "chromePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  "portRangeStart": 9300,
  "portRangeEnd": 9399
}

Environment

| Variable | Default | Description | |----------|---------|-------------| | CHROMUX_PROFILE | default | Active profile name |

License

MIT