Walkthrough

Walkthrough lets an AI agent test your web app in a real, visible browser, one step at a time, with you. After each step, the agent tells you what it did and what you should see. You answer in a small panel in the browser: Pass, Bug, Skip, Retry, or Stop. When you report a bug, Walkthrough saves a screenshot, the console errors, and the network requests. During a test run, it also saves a short video. Then it writes a report.

Walkthrough is a Claude Code plugin with an MCP server inside. The server (uiwalk) controls Chrome with Puppeteer. The plugin adds a skill and slash commands that teach the agent how to test with you. Other MCP clients, such as Claude Desktop, Cursor, and VS Code, can use the server too.

Status: early. Expect changes.

What it does

• Step-by-step testing. The agent does a step, checks it, and asks you to confirm it. You watch in a real browser, and a pulsing box shows each element before the agent uses it.

• Environments. Run the same plans on development, staging, production, or any copy of your app. Each environment has its own address, test data, and passwords, and production asks you before Walkthrough works there. Every report names the environment. See Environments.

• Test plans in YAML. Save a test in .walkthrough/plans/ and run it again later. Your editor gives autocomplete. Three modes set how many steps you confirm: every step, only marked steps, or none. A plan can include another plan, like a shared login.

• A panel you can shape. A plan sets the labels, the buttons and their colors, and a "What's next" part. Panel text can have lists, check lists that you tick, and code. A snippet, like a terminal command, gets a Copy button and a "?" for its help. A step can show a reference image of the page.

• Cards. Start and end messages, as a card in the panel or a big card in the middle of the page. An end card can show only when the run passed, or only when it had problems.

• Faster answers. Keyboard shortcuts, a list of all steps with their results, and a Retry button. "Point at the problem" marks the element of a bug in the screenshot.

• Browser settings. The window fits the page, also for phone and tablet screens in portrait or landscape. Chrome does not ask to save passwords, addresses, or cards. A plan can set the language, downloads, DevTools (also with its device toolbar), extensions, host names, and more. See Settings.

• Reports. Each run writes report.md and a single-file report.html, with bugs first, steps to reproduce, screenshots, and errors.

• Evidence. Screenshots with a red box on the element, console errors, page errors, and Chrome issues. Bugs also get a HAR file of the network requests and a video clip of the last seconds.

• Record mode. Use the app yourself, and Walkthrough turns your clicks and typing into a draft plan.

• Videos. Ask for "a recording demo of the checkout workflow", and get a clean MP4 and GIF with captions and a pointer. Record part of a session, save GIFs for your docs, or make the video again in CI. Videos blur secrets that a page shows, and the parts that you name. See Videos.

• Live presentations. Show a flow to your team or your customers. The app plays step by step in an audience window, with a spotlight, a pointer, captions, and slides. You control it from a presenter window with your notes, a timer, and a chat where the agent answers questions about the app. You get a handout and a video. See Presentations.

• Accessibility reports. Check one page or many with axe-core, a keyboard walk, dark mode, and reflow checks. Get scores, a short explanation and fix for each issue, and a prompt to plan the fixes in a new session. See Accessibility reports.

• Lighthouse reports. Check the performance, best practices, and SEO of pages or of a user flow, with an explanation and a fix for each issue. See Lighthouse reports.

• DevTools for the agent. The agent can read network requests and cookies, and see the CSS rules and event listeners of an element. It can also answer API requests with test data.

• Tabs and logins. Test two users at the same time, each in a tab with its own login.

• More checks. Visual checks against saved baselines, phone and tablet screens, dark mode, slow networks and CPUs, time zones, and languages.

• Sharing. Export a run as a plain Puppeteer script for CI. Turn a bug into a GitHub issue draft.

Related MCP server: MCP Playwright Server

Safe by default

• Walkthrough opens only the sites that you allow. By default, that is localhost. A protected environment, such as production, needs your OK first.

• Passwords go in .walkthrough/.env and appear in plans as {{secret:NAME}}. The agent never sees the values. The panel never shows them, and videos blur them.

• Chrome does not offer to save passwords, addresses, or cards, and it says no to camera, location, and notification prompts. A plan can turn each one back on.

• Walkthrough never runs terminal commands. A plan step can name one, and the agent asks you first.

• Text from web pages is marked as data, so the agent does not follow instructions from a page.

• Page scripts cannot see the panel or fake your answers.

• The tool that runs page JavaScript is off unless you turn it on for yourself.

Read more in Safety.

Requirements

• Node.js 22.19 or later

• Google Chrome. If it is missing, /walkthrough:doctor can download Chrome for Testing.

• Claude Code, for the plugin. Other MCP clients can use the server alone.

• Optional: Lighthouse, for Lighthouse reports, and ffmpeg, for MP4 videos when Chrome cannot make them. Install them from a terminal when you need them. /walkthrough:doctor shows the commands.

Quick start

1. In Claude Code, install the plugin:

   Note: Install the plugin from Claude Code in a terminal. Start Claude Code with the claude command, and then type the commands below. Do not install the plugin from the IDE extension or the desktop app. After the install, the plugin also works in the Claude Code extension for VS Code.

   /plugin install walkthrough --marketplace mrigsby/walkthrough

   This command needs Claude Code 2.1.275 or later. With an earlier version, add the marketplace first, and then install the plugin:

   /plugin marketplace add mrigsby/walkthrough
   /plugin install walkthrough@walkthrough

   Update the plugin. To get a new version later, run these commands in a terminal, and then restart Claude Code:

   claude plugin marketplace update walkthrough
   claude plugin update walkthrough@walkthrough

   The first command gets the newest list of versions. The second command installs the newest version. Run claude plugin list to see the version that you have.

2. Start your app. Then, in your project, set up Walkthrough with the address of your app:

   /walkthrough:init http://localhost:3000

3. Run the sample plan. Chrome opens, and the panel asks you to confirm the step:

   /walkthrough:run smoke

4. Ask for a real test in plain words, such as "walk me through the checkout and ask me to confirm each step". Or write a plan with /walkthrough:plan.

The getting started guide has the details.

Commands

You can also ask in plain words. The walkthrough skill loads when you ask the agent to walk through, click through, or visually test a page.

Files in your project

.walkthrough/
  config.yaml        Settings. Commit it.
  config.local.yaml  Your own settings. Git does not track it.
  plans/             Test plans. Commit them.
  plan.schema.json   Autocomplete for plans. Commit it.
  baselines/         Screenshots for visual checks. Commit them if your team shares them.
  exports/           Puppeteer scripts from runs.
  .env               Secrets. Git does not track it.
  .env.staging       Secrets of one environment. Git does not track it.
  sessions/          Saved logins. Git does not track them.
  runs/              Results and reports. Git does not track them.

Documentation

• Getting started

• Test plan format

• Settings

• Environments

• Videos

• Presentations

• Accessibility reports

• Lighthouse reports

• Tools

• Safety

• Use with other tools and share with a team

• Troubleshooting

Work on Walkthrough

See Contributing. In short:

npm install
npm run build
npm test
npm run demo

The demo shop in examples/demo-app has bugs on purpose, so you can try every feature.

License

MIT. See LICENSE.