sessions

chrome-use — Sessions & Parallel Browsers

Run several isolated browser sessions at once, adopt a stranded tab across sessions by its CDP targetId, and reset stuck session daemons.

Run multiple browsers in parallel

Each --session <name> is an isolated browser with its own cookies, tabs, and refs. Useful for testing multi-user flows or parallel scraping:

chrome-use --session a open https://app.example.com
chrome-use --session b open https://app.example.com
chrome-use --session a fill @e1 "[email protected]"
chrome-use --session b fill @e1 "[email protected]"

AGENT_BROWSER_SESSION=myapp sets the default session for the current shell.

Concurrent agents MUST each use a distinct --session <name>. Within one session, commands are pinned to the tab you opened (by target_id, so a foreign tab can't drift your eval/screenshot). Two agents sharing the same session (e.g. both on the bare default) share one daemon and one active tab and will clobber each other.

True multi-agent isolation requires the extension-connect path: each --session gets its own colored Chrome tab group, so sessions never touch each other's tabs. Raw --cdp <port> does NOT isolate — every session attaches to the same browser's existing targets, so a second session's first open can navigate a sibling's tab. For concurrent agents on one real Chrome, use the extension (each with a distinct --session), not raw --cdp.

Each session owns its own tab group and assigns its own t<N> indices (the same physical tab is t8 in one session, t1 in another), so t<N> is not a stable cross-session handle. To reach a specific tab from another session — e.g. a tab that was filled in a session whose handle later died — use the stable CDP targetId:

chrome-use tab list --full --session B   # re-syncs live tabs; prints `target: <id>` per row
chrome-use tab adopt <targetId> --session B # explicitly adopt it, NO reload

tab list re-discovers the live tab set on every call, so a fresh session sees tabs other sessions opened (and re-attached ones), not just its own. Each row is marked created, adopted, or foreign; foreign tabs cannot be selected or closed. Explicitly adopting by targetId lands session B on the stranded tab without reloading it, so a half-filled form survives. Adoption does not transfer permission to close the tab. Created ownership persists across daemon restarts for the same name and connected browser endpoint, so interrupted cleanup can resume. Still, the simplest recovery for a session whose own tab died is to recover that session (reload / re-open / daemon restart).