Your agents get a tab in the Chrome you are already signed in to

Each agent session drives its own background tab in your real Chrome, inside a red Cast tab group. It reads the page as numbered refs, acts on them, and posts every screenshot, console error and failed request into the conversation. You keep working in your own tabs.

Set up once, per machine
1Install the extension

From the Chrome Web Store, in the Chrome profile agents should use.

2Pair it

Click Pair on the setup page or the Browser card in Agent features. Chrome opens the extension; click Pair there too.

3Done

The card reads Chrome connected. Every agent on the machine now uses your Chrome.

Scripting it? cast browser extension setup does the same pairing from a terminal.

MInbox (3)
docs.acme.dev/q4-roadmap
Q4 roadmap
Ship checkout v2
claude · ~/src/shop
$ cast browser do - <<'EOF'
open https://staging.acme.dev/checkout
snapshot -i -s main
fill #e4 "4242 4242 4242 4242"
click #e7
wait --text "Order confirmed"
EOF
Verify the order fix on staging workingclaude
browser do5 steps · stopped at wait open tab watch
acmestagingD
Your order
Trail runner, size 42$128.00
Wool socks, 2 pairs$18.00
Total$146.00
We couldn't place your order. Please try again.
Card number
4242 4242 4242 4242
#e4
Shipping
Standard, 3 to 5 days
#e5
Save this card#e6
Place order
#e7
ERR TypeError: Cannot read properties of undefined (reading 'id')
500 POST /api/orders · 812ms

The order POST returns 500 on staging and the page throws reading the empty response, so the fix never reached this build. Checking the API logs next.

Agent tabs open in a Cast group in your own Chrome

The codecast extension lets agent sessions open tabs in the Chrome you already use. Every agent tab opens in the background, inside a red Cast group. Your own tabs, windows and focus stay where you left them.

DQ4 roadmapCastaCheckout · AcmeSBilling settingsLSign in · Linear
yours
Mail, a doc, a pull request. An agent never touches, closes or brings forward these tabs.
the Cast group · one tab per session
claudeVerify the order fix on staging
codexReproduce the invoice bug
claudeTriage this week's issues

It uses the Chrome profile you are signed into

The agent uses the profile you are signed into, with no cloned profile or copied cookies. If your Chrome can open a page, such as a dashboard behind SSO, a staging site or an admin panel, the agent can read it. Nothing syncs your profile anywhere.

Agent tabs open in the background

cast browser open creates the tab directly at the URL, in the background. Your screen only changes when an agent runs show, which it does when you asked to see the page or must act in it.

One tab per session

open reuses the session's tab. tabs lists this session's tabs and tabs --all every agent's. Several agents can share one Chrome without stepping on each other.

How to tell a tab is being driven

A driven page wears a thin red border (hidden in screenshots), the toolbar icon shows a CAST badge, and Chrome shows its own debugging banner while a tab is attached. stop closes the session's tab when the work is done.

Screenshots and errors in the conversation

Screenshots render under the step that took them, and a failing step comes back with its own context.

Mobile checkout looks brokenclaude
browser shot--annotate
acmestagingD
Your order
Trail runner, size 42$128.00
Wool socks, 2 pairs$18.00
Total$146.00
Card number
1234 1234 1234 1234
[4]
Shipping
Standard, 3 to 5 days
[5]
Save this card[6]
Place order
[7]
each [N] label is snapshot ref #eN, with a legend
browser shotdesktop, then after viewport mobile
acmestagingD
Your order
Trail runner, size 42$128.00
Wool socks, 2 pairs$18.00
Total$146.00
Card number
1234 1234 1234 1234
#e4
Shipping
Standard, 3 to 5 days
#e5
Save this card#e6
Place order
#e7
desktop
acmestagingD
Card number
1234 1234 1234 1234
#e4
Shipping
Standard, 3 to 5 days
#e5
Save this card#e6
Place order
#e7
mobile
browser wait--text "Order confirmed"
✗ "Order confirmed" never appeared
── failure context ──────────
console errors (newest first):
+6.1s ERR TypeError: Cannot read properties of undefined
failed requests (newest first):
500 POST 812ms https://staging.acme.dev/api/orders

A screenshot, inline

Renders under the step that took it, in the thread. It can be one element, the whole scroll height, or a link the agent uploads so you can paste it anywhere.

the agent runs shot

Numbers drawn on the picture

Every button and field on the image gets a number, so you and the agent can talk about "7" and mean the same button.

the agent runs shot --annotate

The same page at another size

The agent can show you the page as a phone, a tablet or an exact size sees it, then put the tab back.

the agent runs viewport mobile

Console errors and failed requests with each failure

A step that fails comes back with the page's console errors and failed requests, newest first, and a picture of what the screen showed.

Controls on each row

open tab brings the agent's tab forward in your Chrome. watch live streams it into a pane beside the thread.

Taking over when a page needs a person

Some pages are yours to handle: a sign-in, a two-factor prompt, a camera permission. The agent says so and waits. You sign in, in the same tab, and it carries on.

id.linear.app/login
LLog in to Linear
Password
Continue
claude · Linear wants a sign-in. Please sign in here and I will continue in this tab.
1

Watch it live

The watch live pill on any browser row streams the agent's tab into a pane beside the thread, with the agent's cursor drawn where each click lands. It only streams while you are looking.

2

Take the wheel

Your clicks and typing go to the page. The agent keeps its session and hears none of it. Esc hands the page back. Try the button on the left.

3

Or bring the tab forward

The open tab pill on the row raises the agent's tab to the front of your Chrome. An agent can do the same once, when you asked to see the page or must act in it, and never on a loop.

What agents use the browser for

Most of it is the work a person does in a browser after writing code: look at the result, read something behind a login, chase a bug report, check a phone layout.

“The save button on settings should show a toast now. Make sure it does.”

In the conversation: A screenshot of the toast under the agent's browser row, or, if "Saved" never shows, the console errors and failed requests that explain why.

what the agent ran
$ cast browser open http://localhost:3000/settings
$ cast browser snapshot -i -s main
$ cast browser do "click #e12" "wait --text Saved" shot

Local connection, audit trail and allowlist

Your signed-in browser gives an agent a lot of access, so the connection never leaves the machine, every site an agent lands on is written down, and a project can limit where agents may go at all.

cast CLI
your agent's shell
websocket
bridge host
127.0.0.1 only
websocketextension connects out
Codecast extension
in your Chrome profile
chrome.debugger
the Cast tabs
that sessions opened

Pairing hands the extension a token once. After that, each side proves it holds the token with an HMAC over a fresh nonce, so the token itself never crosses the socket, and the extension runs nothing for a host that has not proved it. Setup never prints the token in agent output, because that output syncs off the machine.

An audit trail of every origin

The audit trail is always on. It keeps origins, never full URLs, because paths and query strings carry tokens. A refused navigation is on the trail too. The app has no view of it yet; read it in a terminal.

cast browser audit
policy: ~/src/shop/.codecast/workspace.toml [browser] allow (2 entries)
10-04 14:02 https://staging.acme.dev open · tab 1E226C3B
10-04 14:03 https://auth.acme.dev action · tab 1E226C3B
10-04 14:05 ✗ https://pastebin.com open · blocked
3 visit(s), 1 blocked/off-policy

An optional allowlist

Off by default. Turn it on per project, or per machine with browser_allow in ~/.codecast/config.json. An empty list allows nothing. A click or redirect that lands off the list is flagged.

.codecast/workspace.toml
# agents in this repo may only browse these
[browser]
allow = ["*.acme.dev", "http://localhost"]

No silent fallback. If the extension is missing or asleep, commands wait for it, then say what to fix. They never launch a different browser instead.

Dialogs cannot freeze a tab. Alert, confirm and beforeunload dialogs are dismissed automatically; dialogs lists what the page tried to open.

Your tabs are off limits. Agents act on tabs they opened. The extension never adopts a tab group you made.

Using your sign-ins from a cloud host

A session on your cloud host has no Chrome of yours. When it needs a site you are signed in to, the agent asks your laptop to carry that one login across, over SSH, into the host's browser. There is no button for this; the agent does it.

what the agent runs on the host
$ cast browser sync https://grafana.acme.dev
# your most recently seen online laptop carries it
$ cast browser sync --via <device-id> --wait 60 <url>
$ cast browser sync --all # every site, refused under an allowlist
  • Cookies are never printed. The request carries the site's origin and the answer carries counts.
  • Google is the exception. It signs in on its own and cannot be carried.
  • Datacenter IPs get challenged. Google and DuckDuckGo may bot-block a host; Bing works.
  • In the desktop app, an agent can offer you a page as a pane beside the session.

How an agent reads a page and acts on it

From here down is the agent's side: commands it runs, so you never type them. A snapshot is the page's accessibility tree, cut down to what an agent can act on. Each element gets a ref like #e7, and every acting verb takes one, so the agent does not guess at pixel positions or write fragile selectors. Hover a row to see what it points at.

cast browser snapshot -i -s main
$ cast browser click #e7
$ cast browser find "Place order" # then a bare click
acmestagingD
Card number
1234 1234 1234 1234
#e4
Shipping
Standard, 3 to 5 days
#e5
Save this card#e6
Place order
#e7
snapshot -i -s <sel>

Interactive elements only, in one region. Big apps stay cheap to read.

find "Delete (3rd)"

Names are matched on visible text. Namesakes are numbered, and visible elements rank first.

diff snapshot

Only what changed since the last snapshot, so a step's effect is one short read.

read

The page as clean text, for "what does this page say". get text <sel> reads one element.

Refs survive a re-render. Each snapshot records every ref's role, name and position among its namesakes, so when the page refreshes and #e5 goes stale, cast finds the element at the same position again, so the third "Delete" stays the third.

Running several steps in one command

Every cast command spends one to three seconds starting up for about 85 ms of work in the browser. cast browser do runs a whole flow in one process, so an agent that can see three steps ahead pays for one startup across all three.

five commands
one do
CLI start, about 2 s browser work, about 85 msdrawn to scale
one flow, one step per line
$ cast browser do - <<'EOF'
open https://app.acme.dev/settings
find "Sign in"
click
wait --text "Billing"
shot
EOF
  • A step without a ref acts on whatever the last find matched, so a flow reads like instructions to a person.
  • It stops at the first failing step and reports what ran and what never did. --keep-going carries on past it.
  • Each step's result shows in the conversation as one row, with one screenshot at the end instead of a frame per step.
  • Waits watch for a specific state with wait --text, --url, --load or --fn, instead of sleeping for a fixed time.

Command reference

Agents learn these from their instructions; you only need them to script it yourself. Every verb is cast browser <verb>, and cast browser help <verb> prints its flags.

Go
open <url>
The session's tab, created at the URL in the Cast group
back · forward · reload
History
tabs [--all]
This session's tabs, or every agent's
tab new · close · switch
A second page, or another agent's tab on purpose
stop
Close this session's tab
Read
snapshot -i -s <sel>
Interactive refs in one region (-c compact, -d depth, -u urls)
read [--outline]
The page, or a URL, as clean text
text · get text <sel>
One element's text, no eval
find <text>
Elements by visible name; namesakes numbered
diff snapshot
Only what changed since the last snapshot
Act
click · hover · focus
On a #eNN ref or a CSS selector
type <ref> <text> [--submit]
Type, then Enter
fill · select · press
Fields, dropdowns, keys
scroll · drag · upload
Scrolling, dragging, file uploads
wait --text|--url|--fn
For text, a URL or a JavaScript condition
Prove
shot [--annotate] [--full]
Inline in the conversation
shot -s <sel> · --share
One element, or a link to paste elsewhere
console · errors
What the page logged and threw
network requests · har
Requests, routing, HAR capture
vitals · a11y · record
Web Vitals, axe audit, WebM video
Run
do <steps…> | do -
Many steps, one process (--keep-going)
eval <js> | --stdin
JavaScript in the page; promises awaited
viewport <size> [--reset]
desktop, laptop, wide, tablet, mobile, mobile-small
shots on|off
Auto screenshots after page changes
dialogs
What the page tried to open
Set up
extension setup · status
Pair once; check the connection
show
Raise the tab, when you must act
audit [--all]
Origins visited
sync [url]
Carry a login to a cloud host
chrome restart · launcher
Run Chrome so agent tabs keep normal priority

Requirements and limits

›What does it need?

Desktop Chrome 116 or later, the Codecast extension installed in the profile you want agents to use, and paired once with the computer: click Pair on the Browser card in Agent features, or on the setup card that appears under an agent's step when Chrome is not connected. Chrome has to be running.

›Which pages can it not drive?

Pages Chrome walls off from every extension: chrome://, chrome-extension://, and the Chrome Web Store. open says so before trying, and the agent hands you the URL and the steps instead.

›Why is it sometimes slow?

Chrome throttles background tabs, and on a busy machine a hidden tab can go quiet for tens of seconds. Steps report what they are waiting on. Restarting Chrome through codecast (cast browser chrome restart) adds the switch that keeps agent tabs at normal priority, and agents batch steps to cut the rest.

›Can an agent read my other tabs?

Agents are told to act only on tabs they opened, and the CLI lists and reuses only the session's own. The extension does hold Chrome's debugger permission, since that is what drives a tab, which is why every attached tab is marked, why the connection is local and token proven, and why the audit trail exists.

›What stays with you?

Sign-ins, two-factor codes, and camera, microphone and clipboard prompts. The agent asks; you act in the same tab or through the wheel.

›Is there a separate agent browser?

Only if you explicitly ask for one. Your Chrome is the default every time, including before pairing and after restarts; a missing extension shows you a setup card and does not switch to another browser.

Get started with the browser

The Browser card on the Agent features page: a Cast tab beside your own, the On badge and its switch, and the line Agents check their own UI work in your Chrome, with your sign-ins.
The Browser card in Agent features, switched on.
Script
curl -fsSL codecast.sh/install | sh
Taking longer than usualOffline · reloads when back