How to run a visual review with Claude Code (step by step)

The loop below is short on purpose: record, hand over, verify. What makes it worth setting up is the arithmetic at the end of it — narration and a handful of pointed frames cost the agent a fraction of what the same review costs as raw pixels, and every step is either free or measured. For the wider category this sits in, and the alternatives to Walkie, start with what visual feedback for AI coding agents is.

Install the Claude Code integration#

Open Walkie's Connect your AI step and press Install Claude Code integration. One action registers the walkie MCP server at user scope and installs the walkie-review skill. It can be re-run at any time from Settings, so a broken setup is one button, not a reinstall.

1. Grant the three permissions Walkie asks for: Screen Recording (captures the region, window or display), Microphone (records narration), and Speech Recognition (transcribes it on-device).
2. Quit Walkie with Cmd+Q and reopen it. macOS requires a relaunch before a freshly granted Screen Recording permission takes effect, which is the single most common reason a first recording refuses to start.
3. Press Install Claude Code integration in the Connect your AI step.
4. Start a new Claude Code session. Claude Code reads its MCP configuration when a session starts, so an already-open session will not see the new tools.

User scope is the part worth understanding. Anthropic's Claude Code MCP documentation stores user-scoped servers in ~/.claude.json and makes them available across every project on the machine while keeping them private to your account — so the integration follows you between repositories. The skill lands in the equivalent place: Anthropic's skills documentation puts personal skills at ~/.claude/skills/<name>/SKILL.md, applying to all your projects, with the frontmatter description telling Claude when to load it.

For any client other than Claude Code's own button — another MCP-capable client, or a dev checkout — add the server manually, exactly as Walkie's docs give it. The shape of this block is the same everywhere, because it is defined by the Model Context Protocol rather than by Walkie:

{
  "mcpServers": {
    "walkie": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/walkie/mcp/server.mjs"]
    }
  }
}

Record: talk, point, draw#

Press Cmd+Shift+R anywhere on the Mac to start, and press it again to stop. Before recording begins, a picker scopes the capture to one window, one app, or a whole display — choose the narrowest thing that contains the bug. Then narrate the problem out loud while your cursor sits on it.

1. Talk. Say the location, what you expected there, and what is happening instead. That three-part shape is what makes feedback actionable, and it is covered properly in how to give feedback to Claude Code that lands.
2. Point. Dwelling the cursor near what you are describing is enough to mark that moment as a frame worth keeping. Cmd+Shift+M marks one explicitly. You never have to think about taking a screenshot mid-recording — pointing is the capture mechanism.
3. Draw, when a still says it better. Cmd+Shift+E takes a screenshot, and Control+Cmd+Shift+D captures a region. Every screenshot opens in Walkie's annotation editor with eight tools — Comment, Pen, Arrow, Box, Highlight, Text, Blur and Crop — and a numbered comment pin becomes a comment in that screenshot's markdown sidecar.

While it is rolling, a small capsule sits top-center of the recorded display with a recording dot, a timer and a live mic meter; hovering it reveals a Capture button and the stop control. On stop, Walkie exports the bundle to ~/Walkie/<timestamp>-<slug>/, writing REVIEW.md and a SAVINGS.md note.

Hand the bundle to the agent#

Give Claude Code the bundle path — ~/Walkie/<timestamp>-<slug>/REVIEW.md — or just ask it to review your recording. The walkie-review skill triggers on phrasings like "review my recording" or a path containing /Walkie/, and it tells the agent how to read the bundle without burning tokens on it.

REVIEW.md is plain markdown with a fixed shape: a title and note, a short "How to read this (for Claude)" block addressed to the agent, a token-cost line, the full transcript with frame references inline at the moments they were captured, a frame index table, and a duration line. Nothing in it needs a video player, which is the entire point — the recording is scaffolding, the bundle is the deliverable. The format is unpacked in what a REVIEW.md bundle actually is.

What the skill instructs, in order: read REVIEW.md fully first; answer from the transcript wherever possible, because most questions are answerable from the words alone; open only the frames whose moments relate to the question, preferring as few as possible; never open the recording video file, which exists for humans; and end with a line stating what the review cost in tokens.

Verify the fix, then re-record if needed#

Re-run the exact check that surfaced the bug — same screen, same input, same state — and confirm the expectation you named out loud now holds. The agent saying it is fixed is not confirmation. Matching the observed result against the expectation you stated is.

Verification is the step people skip because watching an agent report success feels like evidence. It is the same verify step as in the plan, execute, verify loop, and for UI work specifically the states most reports miss — empty, loading, error, long text — are enumerated in the checklist for verifying AI-built UI.

If it is still wrong, re-record only the part that changed rather than the whole flow again. A shorter recording produces a smaller bundle and, more usefully, a narrower one: a 10-second clip of one element is a clearer instruction than a second full tour with the fix folded into it. Start the new recording from the state where the problem now appears, not from the beginning of the journey to it.

What each step costs#

Only two steps in this loop cost model tokens at all: the agent reading the bundle, and any screenshot you paste by hand afterwards. Recording and transcription run on your Mac and send nothing to a model.

Both 2,691-token figures are the high-resolution tier — Claude 4.7 and later — where a single image is capped at 4,784 tokens; standard-tier models downscale the same 1080p image to 1456x819 and pay 1,560. Anthropic's patch formula is the ceiling of width over 28, times the ceiling of height over 28, per Anthropic's vision documentation; price your own resolution in the screenshot token cost calculator.

One thing the table understates. None of these costs are paid once — the conversation is resent with every request, so whatever you hand over on turn one is still in the bill on turn twenty. That is the subject of why UI work burns more Claude Code tokens than backend work, and it is the strongest argument for handing over 3,500 tokens instead of 80,730.

Common mistakes#

Six things break this loop, and the first four are setup rather than technique — worth checking in order before assuming the recording itself was the problem.

1. The Claude Code session was already open. MCP configuration is read at session start. Start a new session after installing.
2. Walkie is closed. The five recording tools call a local control API that only runs while the app is open. The two screenshot tools read disk directly and keep working either way.
3. Screen Recording was just granted. macOS needs Walkie quit with Cmd+Q and reopened before the permission takes effect.
4. The whole desktop got recorded. The picker scopes to a window, an app, or a display. A narrower scope means fewer irrelevant pixels in every frame that gets kept.
5. The narration named a feeling, not a target. "This looks off" gives the agent nothing to check itself against. Name the location, the expected state, and the gap, out loud, in that order.
6. The agent was asked to open the recording. It should not, and REVIEW.md tells it not to. If a moment has no captured frame, the honest answer is that it was not captured — point at it and record ten more seconds instead.