Let your coding agent use a browser

Have your coding agent check its own work and show you screenshots. Then you annotate what to change instead of describing it.

Download for macOS

You'll need the bb desktop app for Browser tabs, logins, and annotations.

Hand this to your agent
Ask me about each of these, one at a time, with a suggested default:
- App URL (e.g. http://localhost:3000)
- Flow to check (the change to click through)
- Screen sizes (e.g. desktop and phone)
- Needs a sign-in (yes or no)
Skip any I've answered. Then sum up the plan in three bullets and wait for my go. My answers override the steps below.
If a wait times out, wait again, up to three times.

Use a real browser to check my app, click through the change, and show me screenshots.
Guide: https://getbb.app/guides/agent-browser

Do every step below, with a Check after each step. Stop if a check fails and tell me what failed. Don't commit, push, or deploy unless I ask.

1. Set up browser access. Run bb plugin list. Browser Automation isn't installed by default: install it with bb plugin install browser-automation --yes if it's missing, or enable it with bb plugin enable browser-automation if it's off. Agent Annotations is built in but off: enable it with bb plugin enable agent-annotations. Then read bb guide browser and bb browser-automation --help. Find this thread's machine with bb status --json and bb machine list.
   Check: both plugins are running and the chosen browser machine is connected.

2. Open the app.
   2a. If the App URL needs a dev server, start it with the project's documented command in a bb terminal in this environment, and check that the URL responds.
   2b. If Needs a sign-in is no, open headless Chrome on that machine:
   bb browser-automation open --backend local --headless --machine <host-id> --json
   2c. If Needs a sign-in is yes, use the desktop app's Browser instead: run bb browser instances --host <desktop-host-id> --json, select the intended connected desktop instance, then:
   bb browser-automation open --backend desktop --machine <desktop-host-id> --desktop <instance-id> --json
   Ask if the intended desktop instance is ambiguous. Localhost means the browser's machine; use a reachable app URL if it differs from the dev server's machine. Keep the returned session ID. Emit the returned previewDirective once if present. Use bb browser-automation run to get a named page, navigate, and snapshot it; follow bb guide browser for the script format. Each run times out after 30 seconds by default.
   Check: the page shows the intended app. For a signed-in flow, verify the expected account. If signed out, use bb browser import-sources with the selected host, instance, and generation to discover sources. Ask me which source/profile to use, then run bb browser import-cookies with those exact values. If the source browser needs quitting, an OS prompt needs my input, or login is still needed, stop with that specific next action. Never read or print cookie values. Import is desktop-only and doesn't populate headless sessions.

3. Verify the change. Take a fresh snapshot, click through the requested flow using its element references, and check the visible result. Check the console and the layout at each size in Screen sizes. Use bb browser-automation screenshot <session-id> --page <name> --json and inspect the returned images. Show the screenshots that matter in this thread as images; for another browser host, fetch them with bb file read. Fix failures within the requested change and recheck the affected flow.
   Check: the flow behaves as requested, the layout works at each size, and any console errors are explained. Report what you actually exercised and show the screenshots; don't call a screenshot alone a passing interaction test.

4. Leave the app ready for feedback. Close the automation session with bb browser-automation close <session-id> and keep the preview server running. In desktop bb, use bb browser create with the selected host, instance, generation, current thread, URL, and --reveal to leave a Browser tab open for annotations. If no desktop instance is connected, explain that element annotations require the desktop app and give me the app URL. Tell me to choose Annotate elements, click the element, write the change, and choose Add to prompt. When I send an annotation, use its element context to make the change and verify it in a new browser session.
   Check: the automation session is closed, the preview route still responds, and the feedback tab is open when desktop is available. Report the URL, terminal ID, browser machine, screenshots, and anything you couldn't verify.

Then offer to save these steps as a bb skill in .bb/skills/check-in-browser/SKILL.md, with my App URL, dev server command, sign-in, Screen sizes, and browser machine filled in, so next time I can just ask for it.

Steps

  1. 1Add the browser plugins
  2. 2Import your browser logins
  3. 3Ask your agent to try its change
  4. 4Point at what to change
1

Add the browser plugins

The Browser Automation plugin gives your agent a browser. The Agent Annotations plugin lets you point at what you mean.

  1. Choose Plugins in the sidebar, search for “browser”, open Browser Automation, and choose Install. It's made by bb but isn't installed until you add it.
  2. Agent Annotations comes with bb, turned off. In the same list, open Agent Annotations and turn on its switch.
2

Import your browser logins

Your agent can open the sites you use, logged in as you.

  1. In the bb desktop app, open Settings → Browser.
  2. If a browser shows Running, quit it and choose Recheck.
  3. Choose Import… next to your browser, like Chrome, and pick a profile.
3

Ask your agent to try its change

Give it a flow to exercise and the screen sizes you care about.

Example
I just added status filters to the Orders page. Start the dev server, open the app in a browser, and try the filters at desktop and phone sizes. Fix anything broken, and show me screenshots.

Your agent starts the dev server, opens a browser, and clicks through the flow. A live preview in the thread lets you watch.

See the screenshots

Ask for them in the thread, like “show me the phone screenshots before and after, side by side.” Here, the agent found the search box and Total column cut off on a phone, fixed the CSS, and posted both.

4

Point at what to change

Select the element instead of describing where it is.

  1. Open the side panel (⌘ J), choose , then Open browser, and enter your app's address. Or ask your agent to open it.
  2. Choose Annotate elements in the toolbar and click the element.
  3. In the box, write your note and choose Add to prompt. Add as many as you like, then send.

Troubleshooting

Browser Automation isn't in my installed plugins
  1. It's not installed by default. Choose Plugins, search for “browser”, and open Browser Automation.
  2. Choose Install, then confirm. It turns on right away.
I don't see Annotate elements
  1. Use the bb desktop app. Annotations only work in a Browser tab there, not in the web app or the live preview in a thread.
  2. In Plugins, open Agent Annotations and turn on its switch.
  3. If your agent is using the tab, choose Take over first.
The browser won't start
  1. Check that the machine is connected in Settings → Machines.
  2. The first run installs the browser tools on that machine, so it needs network access and npm. A fresh browser also needs Chrome or Chromium installed there.
  3. For a Browser tab, keep the bb desktop app open, then ask again.
The site still asks me to sign in
  1. A fresh browser starts signed out. Ask your agent to use a Browser tab instead.
  2. Import from Settings → Browser again. Importing copies your logins once, so newer logins don't carry over.
  3. Still signed out? Sign in once in a Browser tab. It stays signed in.
I can't import from my browser
  1. Quit that browser completely, then choose Recheck.
  2. For Safari, choose Grant access… and turn on Full Disk Access for bb. Chrome may ask for Keychain access; allow it.
  3. Choose Refresh to look for browsers again.
The live preview says Ended

Your agent closed its browser, or it sat unused for five minutes. The thread keeps the last view. Ask your agent to open it again.

FAQ

Can it test my app at phone sizes?

Yes. Ask for the sizes you care about, like “desktop and iPhone.” The agent resizes the browser and takes a screenshot at each size.

Does my dev server need to run on the same machine?

It's easiest. The agent starts the dev server in a terminal in the thread, then opens it in a browser on the same machine.

Can I point at a Figma design?

Annotations select elements on a webpage, not layers in Figma. Annotate the running app, and attach a screenshot of the design for reference.

Can it do more than test my app?

Yes. The same browser handles research, signed-in dashboards, and forms. See Get research and reports from any site.

Which agents work?

Claude Code, Codex, and Pi are built in. Cursor, opencode, and other agents that support the Agent Client Protocol, like Grok Build and Hermes Agent, work once they're installed.

Do I need the desktop app?

Not for a fresh browser: your agent can open Chrome on any connected Mac or Linux machine, and you watch it in the thread. Browser tabs, your logins, and annotations need the desktop app.

Can I stop the agent or step in?

Yes. A Browser tab shows a bar while your agent controls it. Choose Take over to click and type yourself, like to enter a sign-in code, or Stop to end its control.

Can my agent see my passwords?

No. bb imports your logins, not your saved passwords, so your agent opens sites already signed in without seeing a password. Your logins stay in bb's Browser on this computer, and the prompt from Copy for agent tells your agent never to read or print them.

Can the browser run on a different computer?

Yes. Ask for the browser on the machine you want. There, localhost means that computer, so use an address it can reach.

Does it need macOS Automation permission?

No. Browser Automation talks to Chrome and bb's Browser directly, so it doesn't need Accessibility or Automation permission.

Let your agent check its own work

Free and open source. Use the agents you already have.

Download for macOSApple Silicon · Also for Linux (Alpha)bb runs on macOS, Windows, and LinuxWindows (Alpha), Intel Macs & remote machines