Walkthroughs

A walkthrough is the fastest way to show someone (or an agent) what you mean. Talk through a task as you would to a colleague looking over your shoulder, snap annotated screenshots along the way, and OpenWhisper hands you one document: your words, with each screenshot right after what you said about it.

Record a walkthrough#

1. In Quick Record, choose Start Walkthrough, or press your Walkthrough shortcut, or use the tray's Start Walkthrough.
2. Talk. The recording overlay moves to the top-left corner and counts the screenshots you keep.
3. Whenever you want to show something, choose Snap on the overlay or press Screenshot. The screen freezes; drag out the part that matters and mark it up. Press Enter to keep it or Esc to discard it. The recording keeps going while you draw, so keep talking.
4. Choose Done on the overlay, or press Walkthrough again, to finish.

Cancel throws the whole walkthrough away, screenshots included.

While you record, a column at the right edge of the screen shows your voice as rows of ticks, like lines of writing, with each kept screenshot dropping in below what you said before it. It never takes focus and never appears in your screenshots. Drag it aside if it covers something.

Mark up a screenshot#

Enter or a double-click with no selection takes the whole screen. A snap freezes every monitor, so you can select on any of them.

Paste it into your agent#

Your words are cut into sections at each screenshot, nudged to the nearest pause so no word is split. Each section is transcribed with your usual voice model, dictionary, and AI cleanup. Then OpenWhisper writes a PDF and a Markdown file and copies them:

• Chat apps that take files on paste attach the PDF, words and pictures together.
• Terminal agents such as Claude Code or Codex get the Markdown as text, with each screenshot's full path so they can open it at full resolution.

A card in the corner says when it's ready, with Open, Show in folder, and the PDF as a chip you can drag into any app, handy where pasting a file doesn't work. Default copy on the Walkthroughs page chooses PDF, Markdown, or both (the default).

Everything lives in a dated folder under captures in OpenWhisper's data folder: walkthrough.pdf, walkthrough.md, walkthrough.json, and each shot-N.png. History lists it as Walkthrough.

Shape the document#

Under Document on Settings → Dictation → Walkthroughs, set the title (or leave it empty for none), and turn the date-and-length line, the how-to-read note, and screenshot captions on or off. The PDF's paper follows your region unless you choose Letter or A4. Your words and screenshots are always included.

Let your agent write it up#

Turn on AI write-up and choose Claude Code, Codex, or OpenCode, whichever you have installed and signed in. When a walkthrough finishes, the agent turns it into a cleaner document with a short title, tidy wording, and each screenshot where it helps most. That write-up is what gets copied, in the same PDF style; it usually takes 10 to 60 seconds and runs on your own plan.

• Instructions replaces the default brief with your own.
• Follow notes left for the agent (off by default) lets you direct it mid-recording: “note for the agent: skip the setup part” or “make the headings purple.” The agent follows the note and leaves it out of the write-up.
• The as-spoken PDF and Markdown are always kept. If the write-up fails, the walkthrough is copied as spoken and the status says why.

Review, recover, and clean up#

Quick Record → Saved Walkthroughs… lists finished walkthroughs and interrupted drafts. From there you can:

• Correct any section's text, uncheck an accidental screenshot, and Save review to regenerate the documents. Unchecked screenshots stay listed, faded, so you can put them back.
• Retry AI write-up with your current agent and instructions, without recording again.
• Copy for agent (Markdown) or Copy PDF long after the ready card is gone.
• Recover draft after a crash or power cut: restart OpenWhisper, then recover; the saved audio is joined back to its screenshots and transcribed.
• Set a retention period with Apply retention…. It defaults to Forever, and drafts and unexpected files are never deleted automatically.

Where it works#

The full behaviour, including how words are aligned to screenshots, is in the walkthrough guide.