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

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.

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

To use chromux as agent browser skills, install the CLI and register the two repo-local skills with Codex, Claude Code, or Hermes:

• install.md — CLI install, skill registration, and smoke test
• skills/chromux/SKILL.md — day-to-day chromux CLI usage
• skills/chromux-work/SKILL.md — profile selection, recon, parallel browser work, cleanup, and domain notes
• AGENTS.md — repo guidance for coding agents

# Launch Chrome with an isolated profile (auto-finds Chrome, auto-assigns port)
chromux launch
chromux launch work
# Open tabs for two agents
chromux open agent-a https://news.ycombinator.com
chromux open agent-b https://reddit.com/r/programming
# New tabs are background by default so headed Chrome does not steal focus
chromux open agent-c https://example.com
# Each operates independently
chromux snapshot agent-a
chromux click agent-a @3
chromux run agent-b "return await js('document.title')"
chromux cdp agent-b Runtime.evaluate '{"expression":"location.href","returnByValue":true}'
chromux screenshot agent-a /tmp/hn.png
# Clean up
chromux close agent-a
chromux close agent-b
chromux kill default

chromux defaults to the compatibility-oriented default mode. It preserves the legacy browser behavior and is the right choice for QA, visual checks, login flows, and tasks where the page should behave as much like a normal human-driven Chrome tab as possible.

For crawling, use crawl mode:

CHROMUX_MODE=crawl chromux launch crawl-news --headless
CHROMUX_MODE=crawl CHROMUX_PROFILE=crawl-news chromux open worker-1 https://news.ycombinator.com
CHROMUX_MODE=crawl CHROMUX_PROFILE=crawl-news chromux open worker-1 https://example.com
CHROMUX_MODE=crawl CHROMUX_PROFILE=crawl-news chromux close worker-1

For URL batches, use the same crawl mode with batch:

CHROMUX_MODE=crawl CHROMUX_PROFILE=crawl-news \
 chromux batch --file urls.txt --workers 10 --out results.jsonl

batch reads plain URL lines or JSONL rows with url, source_url, or href, reuses a worker-tab pool, writes one JSON result per URL, and closes worker sessions when done.

crawl mode keeps the public command surface the same, but changes the profile daemon policy:

• caps expensive profile operations (CHROMUX_MAX_CONCURRENT_OPS_PER_PROFILE, default 4)
• caps active sessions (CHROMUX_MAX_SESSIONS_PER_PROFILE, default 12)
• blocks common heavy media, font, and analytics resources
• uses shorter navigation waits (CHROMUX_NAVIGATION_WAIT_MS, default 5000)
• closes idle/stale sessions
• closes CDP-unresponsive sessions so a worker tab can continue with later URLs
• closes initial blank/new-tab targets created during crawl-mode launch
• rejects new work when queue or resource guards are exceeded
• supports chromux pause / chromux resume as a profile hard-stop
• can optionally recycle long-lived worker tabs after a bounded number of navigations
• can optionally compact renderer growth for iframe-heavy crawl pages

For best crawling throughput, use a small worker-tab pool instead of one tab per URL. For example, process 20 URLs through 3 to 5 stable session names and repeatedly call open on those sessions. Reusing a session navigates the same tab instead of creating another renderer.

If an orchestrator needs to stop a wave, pause the profile. Existing close, list, and stop still work, but new browser work is rejected until resumed:

CHROMUX_PROFILE=crawl-news chromux pause
CHROMUX_PROFILE=crawl-news chromux resume

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://...
# Auto-launch headed Chrome, then keep new tabs in the background by default
CHROMUX_LAUNCH_MODE=headed chromux open bg-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

chromux intentionally keeps the visible command surface small. When a new browser operation is needed, express it with run or cdp before adding another verb.

run scripts execute in an async function context:

chromux run s - <<'JS'
await cdp('Page.navigate', { url: 'https://example.com' });
await waitLoad();
return await js('document.title');
JS

run executes in the runner context, not directly inside the page. Use js(...) for page expressions or page(...) for common page metadata:

chromux run s - <<'JS'
return await page('({url:location.href,title:document.title,textLength:document.body.innerText.length})');
JS

cdp is a thin passthrough:

chromux cdp s Runtime.evaluate '{"expression":"navigator.userAgent","returnByValue":true}'

The older eval, scroll, wait, console, network, and scroll-until commands remain available for existing automation and do not print deprecation warnings. They are intentionally hidden from the main help surface.

scroll-until is now documented as runner material in snippets/_builtin/scroll-until.js; copy or adapt that file when a task needs the pattern.

~/.chromux/
 config.json Global config (optional)
 profiles/
 default/ Chrome user-data-dir
 .state PID, port, socket path cache
 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
• Profile adoption — .state is a cache, not the source of truth; chromux ps, launch, open, and kill rediscover live Chrome processes from --user-data-dir + CDP when daemon/socket/state files drift or disappear

Optional ~/.chromux/config.json:

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

chromux supports two Chrome launch modes:

• headless: no visible Chrome window. This is the default auto-launch mode unless CHROMUX_LAUNCH_MODE is set.
• headed: normal visible Chrome window.

By default, chromux open creates new tabs in the background so a visible headed profile does not come to the front for each new session:

chromux launch work
CHROMUX_PROFILE=work chromux open tab https://example.com

Per-command equivalents are available:

chromux open --background tab https://example.com
chromux open --no-focus tab https://example.com
chromux open --foreground tab https://example.com

MIT