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 "alice@test.com"
chrome-use --session b fill @e1 "bob@test.com"

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).

To avoid piling up duplicate tabs when you re-open the same entry URL on rebind, pass --reuse-tab: if a tab already shows that URL (matched by origin+path), it switches to it instead of spawning a new one.

Reset stuck daemon state

Each session runs a background daemon worker that holds the page handles. If a session starts misbehaving — commands hit the wrong tab, refs/handles look stale, or you upgraded chrome-use mid-session and old workers linger — restart the daemons instead of hunting PIDs with pgrep/kill:

chrome-use daemon status     # list running session daemons (+ relay state)
chrome-use daemon restart    # kill every session daemon worker

daemon restart leaves the extension's native-messaging bridge (__nm-host) alone, so the relay to your live Chrome stays up — the next command just spins up a fresh, clean daemon against the same browser. It does not close any tabs. Start with chrome-use status, which does not contact the daemon. Debugger calls through the extension have a bounded timeout; if an older extension leaves the session silent until the CLI socket deadline, chrome-use automatically stops that stuck daemon and tells you to rerun or adopt the tab. If the daemon process is still alive but its local socket has disappeared, the next browser command reclaims it and starts a clean replacement for the same session. If the socket disappears during an in-flight command, rerun that command after chrome-use clears the stale state.

Hand a session to the human (rare escape hatch)

Autonomous login is the default — drive the login flow yourself. session handoff is only for the one step the agent genuinely can't do (a device 2FA prompt, a CAPTCHA the humanizer can't clear), not a login method.

chrome-use session handoff       # give THIS session to the user; agent driving commands refuse (exit 1)
chrome-use session status        # who owns each session (agent | user)
chrome-use session list          # all sessions + owners
chrome-use session resume        # take the session back once the human is done

While a session is handed off, its owner sidecar (.owner) flips to the user and every driving command (click/type/eval/…) refuses with a loud exit-1 error so the agent can't fight the human for the page. resume returns control. Ownership is per-session, so other sessions keep working normally.