Skip to content
New: answer your agents from your phoneLearn more

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.

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 screenshot
  1. open loads the page in the worktree's tab, and opens a tab first if there isn't one. localhost:5173 stands for http://localhost:5173.
  2. snapshot -i lists the page's buttons and fields, each with a ref like @e4. A ref keeps working until the page loads another document.
  3. fill and click act on those refs. click scrolls the element into view first, and refuses with a reason if something covers it.
  4. wait holds 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.
  5. console --errors prints the page's console errors, oldest first, and folds repeats into one line.
  6. screenshot saves 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 stop

record 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.
  • snapshot can'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.