Workspaces & tab groups

Named Chrome windows so multiple agents work in parallel without colliding — or with you.

One browser, several actors: you, and however many agents you've got running. Workspaces keep them out of each other's way.

Workspaces — named windows#

chrome-relay workspace create research          # opens a new Chrome window, names it
chrome-relay workspace list                     # name, windowId, tabCount, alive
chrome-relay workspace close research

Every command accepts --workspace <name> to target the active tab in that window:

chrome-relay --workspace research navigate "https://chrome-relay.kushalsm.com" --new
chrome-relay snapshot --workspace research -i
chrome-relay screenshot --workspace research -o out.png

The pattern this enables: give each agent its own workspace. Agent A drives the research window, agent B drives checkout-flow, and your own window is never touched. Since everything runs on background tabs anyway, none of them steals your focus.

Tab groups — folders inside a window#

chrome-relay group create sources --color blue --tab 42   # Chrome's native colored groups
chrome-relay group add sources --tab 43 --tab 44
chrome-relay group list
chrome-relay group remove sources --tab 43
chrome-relay group close sources                          # closes the group's tabs

And --group <name> targets the active tab inside a group, same as --workspace.

Groups are lighter than workspaces — same window, visual organization, one collapse-click for the human watching. Use workspaces for isolation between agents; use groups for organizing one agent's working set.

Targeting rules (strict on purpose)#

• Exactly one of --tab / --workspace / --group per command. Two at once is target_conflict, not a guess.
• Subcommand-level flags override program-level ones, and the override is announced on stderr (target_overridden) so it's never silent.
• Ref actions ignore all of this — a ref carries its own tab, and combining it with --workspace/--group is target_conflict.

Viewport per tab#

Emulation composes with all of it — each tab can hold its own device profile:

chrome-relay viewport preset iphone-14 --workspace research
chrome-relay viewport set --width 390 --height 844 --dpr 3 --mobile --touch --tab 42
chrome-relay viewport clear --tab 42

Survives navigation, cleared when the tab closes. Useful for checking responsive layouts in one window while desktop work continues in another.