Docs

Install

Download the Walkie DMG, open it, and drag Walkie into your Applications folder. The build is signed and notarized with an Apple Developer ID, so Gatekeeper opens it with no right-click workaround.

Requirements: macOS on Apple Silicon.

Permissions

macOS gates screen and microphone access per app. Walkie asks for three permissions, each used for exactly one thing:

Permission	Why Walkie needs it
Screen Recording	Captures the region, window, or display you're reviewing.
Microphone	Records your spoken narration while you point at what's wrong.
Speech Recognition	Transcribes that narration on-device — this is what makes the transcript in REVIEW.md possible.

One thing worth knowing up front: macOS requires quitting and reopening Walkie (⌘Q, relaunch) before a freshly-granted Screen Recording permission actually takes effect. If a recording won't start right after you flip the toggle in System Settings, that's why.

Your first recording

Press ⌘⇧R (Cmd+Shift+R) anywhere on the Mac to start recording — press it again to stop. Before it starts, Walkie's one-click picker lets you choose exactly what to record: a specific window, an app, or a whole display.

Once it's rolling, a small capsule — the Notch Pill HUD — appears top-center of the recorded display: a breathing rec dot, a running timer, and a live 5-bar mic meter. Hover it to reveal a Capture button and the stop control.

Just talk and point. Dwelling your cursor near something you're describing is enough to mark that moment as a frame worth keeping — you can also press ⌘⇧M (Cmd+Shift+M) to mark a moment explicitly. You never have to think about "taking a screenshot" mid-recording; pointing is the capture mechanism.

Stop the recording the same way you started it. Walkie exports the bundle to ~/Walkie/<timestamp>-<slug>/, writing REVIEW.md (the transcript, with your pointed frames inlined at the moments they happened) and SAVINGS.md (the tokens you saved versus a frame-dumped screen recording).

Connect your AI

Walkie's first-run setup has a "Connect your AI" step with a one-click Install Claude Code integration button. It registers the walkie MCP server at user scope — every project, not just the one Walkie happened to launch from — and installs the walkie-review skill, in one action. You can re-run it any time from Settings.

Two things worth knowing about that connection:

• Walkie has to actually be open for Claude Code's walkie_* tools to work — they talk to a local control API the app runs while it's running.
• Claude Code reads its MCP config when a session starts. If a session was already open when you clicked Install, start a new one to pick up the new tools.

For any setup other than Claude Code's own button — another MCP-capable client, or a dev checkout — add the server to that client's MCP config manually:

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

(A packaged install can also run through Walkie's own bundled runtime instead of a system Node — mcp/install.sh --dry-run prints the exact command for your install.)

The bundled walkie-review skill installs to ~/.claude/skills/walkie-review/SKILL.md. It teaches Claude Code how to read a bundle without burning tokens on it: read REVIEW.md fully first, answer from the transcript wherever possible, and open only the specific frames a question actually needs — never the raw recording file.

Reading the bundle

Every bundle's entry point is REVIEW.md — the full transcript with your pointed frames referenced inline, plus a frame index. That's deliberately (almost) all your agent needs; the frames are supporting evidence, not the primary signal. For the full reasoning behind that format, see what a REVIEW.md bundle actually is.

MCP tool reference

The walkie MCP server exposes seven tools. The first five need Walkie open (they call its local control API); the two screenshot tools read files on disk directly and work whether or not Walkie is running.

Tool	What it does
walkie_start_recording	Start a new recording scoped to a window, app, or display (or the primary display if none is given); optionally set a token budget and a note.
walkie_stop_recording	Stop the active recording and finalize its bundle — returns the bundle path, the REVIEW.md path, and the token cost.
walkie_recording_status	Check whether Walkie is currently recording, idle, or exporting.
walkie_list_recordings	List past recordings (id, name, created time, duration, token cost), most recent first.
walkie_get_review	Get the REVIEW.md path for a finished recording by id.
walkie_list_screenshots	List recent screenshots — path, capture time, dimensions, annotation status — newest first. Works even if Walkie isn't running.
walkie_get_screenshot	Get one screenshot by path or id: the image path plus its markdown sidecar, including any numbered comments left on it.

Screenshots & annotation

Screenshots are the lighter-weight capture: press ⌘⇧E (Cmd+Shift+E) for a full/window screenshot, or ⌃⌘⇧D (Control+Cmd+Shift+D) for a region variant when you only need part of the screen. Screenshots aren't metered by the free tier — only recordings are.

Every screenshot opens in Walkie's annotation editor, with eight tools:

Tool	Shortcut	What it's for
Comment	C	Drop a numbered pin with a note — the note becomes a comment in the screenshot's markdown sidecar.
Pen	P	Freehand drawing.
Arrow	A	Point at something specific.
Box	R	Outline a region.
Highlight	H	Call out an area without obscuring it.
Text	T	Add a text label directly on the image.
Blur / redact	B	Hide something sensitive before you share the screenshot.
Crop	X	Trim the image to just the part that matters.

Free tier & license

Walkie's free tier is two independent lifetime counters — 7 screen recordings and 10 screenshots, ever, with no daily reset and no expiry. No account, no card, needed to use it. Once you've used your 7 recordings or your 10 screenshots, that counter is done; the other keeps working until it's also used up.

A $39 one-time license removes both caps, for one person on every Mac they own, and includes every v1.x update. To activate, paste your key (it looks like WALKIE-XXXX-XXXX-XXXX) into Settings → License and press Activate — Walkie stores the activation locally and re-validates it periodically.

Troubleshooting

A permission stopped working after an update. macOS ties permission grants to the app's exact build in some cases, so an update can require re-granting Screen Recording. Re-enable it in System Settings → Privacy & Security → Screen Recording, then quit (⌘Q) and reopen Walkie — the same relaunch step first-run setup calls out.

Something's not working and you're not sure why. Walkie keeps a log file at ~/Library/Logs/Walkie/walkie.log. It's the first thing worth checking — and worth attaching if you're reporting an issue.