Test a local web app with a coding agent.
An agent that can open your app in a browser can check its own work: load the page, click through the change, read the console and show you a recording. ket gives each worktree a Chromium tab the agent drives from its terminal.
Published
Why an agent should test in a browser
A coding agent that only reads code calls a change done once the build passes. A passing build won't show it the new button hidden under a cookie banner, or the form posting to a route you renamed last week, and you find those later when you open the page yourself.
Give the agent a browser and it can run the loop you would: start the dev server, open the page and try the change, then read the console, fix what broke and look again. You could script that loop with Playwright, but then you maintain test code for a change you wanted to see once.
How ket gives an agent a browser
Each worktree in ket can have its own Chromium browser tab beside the agent's terminal. The agent drives that tab with the ket command, which ket adds to the PATH of each terminal it opens. ket sends clicks and key presses as real mouse and keyboard events, and drives the page from inside the app without opening a remote-debugging port.
Each worktree's tab keeps its own sign-ins and site data, so two agents can test two branches of the same app at once without signing each other out. Deleting a worktree deletes its browser data too.
ket tells Claude Code and Codex about ket browser as each session starts. Other agents can run the same commands once you mention them in your prompt or in your AGENTS.md.
Test a sign-up form, step by step
Say you asked an agent to add email validation to a sign-up form. End the prompt with the check you want:
When you're done, start the dev server, open the sign-up page with
ket browser, submit a bad address and a good one, check the console for errors, and record the run.
The agent starts the dev server in its terminal, then runs commands like these:
ket browser open localhost:5173/signup
ket browser snapshot -i
ket browser fill @e4 'not-an-email'
ket browser click @e7
ket browser wait --text 'Enter a valid email'
ket browser console --errors
ket browser screenshotopenloads the page in the worktree's tab, and opens a tab first if there isn't one.localhost:5173stands forhttp://localhost:5173.snapshot -ilists the page's buttons and fields, each with a ref like@e4. A ref keeps working until the page loads another document.fillandclickact on those refs.clickscrolls the element into view first, and refuses with a reason if something covers it.waitholds until the text appears, up to ten seconds by default, and exits with an error if it doesn't. It can also wait for an element, a new address or a page load.console --errorsprints the page's console errors, oldest first, and folds repeats into one line.screenshotsaves a PNG and prints its path, which an agent that reads images can open.
If the page opens an alert, a confirm or a prompt, ket reports what it asks in the next command's output, and ket browser dialog accept or dismiss answers it. ket browser --help lists the rest, including type, press, scroll and eval.
Watch it, or let it record
The agent drives the same tab you see in ket. Leave the worktree on screen and you can watch it type and click, or switch to another worktree and let it work out of sight.
For runs you won't watch, ask the agent to record:
ket browser record start
# ... the steps ...
ket browser record stoprecord stop saves an MP4 of the tab and up to six stills spaced through it, and prints their paths. You watch the video, and an agent that reads images but not video looks at the stills. ket stops a recording after two minutes unless the agent sets a longer limit, up to ten.
Check the page yourself
Open a browser tab in any worktree with ⌘⇧B. The code button in the tab's toolbar opens Chromium's DevTools in a separate window. The camera button sends a screenshot of the page to the worktree's agent with a prompt you write, so you can point at what's wrong.
Limits
- ket has to be open on your Mac. Without it, the commands exit with a message saying so.
- A worktree records one video at a time.
snapshotcan't see inside a frame from another site, and CSS selectors don't search frames. Use refs.- Each worktree's dev server needs its own port. Set up each worktree before two agents run the same app.
What you need
- ket on your Mac, with the agent started in a worktree.
- A web app the agent can start from its terminal, or one already running.
Until ket's first release, you build the Mac app from source. To keep several agents' changes apart while they test, read Run coding agents in parallel.
Related guides
Test an Android app with a coding agent.
Use an Android emulator beside Codex, send screenshot feedback with ⌘S, and capture screens with adb.
Set up a Git worktree for a coding agent.
Dependencies, .env files, ports and databases: what a fresh worktree is missing and how to fill it in.
Run coding agents in parallel without sharing a working directory.
How to split work between agents, watch them, and merge the results one at a time, smallest dependency first.
AGENTS.md vs CLAUDE.md: one instruction file for every agent.
Which agents read AGENTS.md or CLAUDE.md, how to keep one file for all of them, and how to keep it lean.