# Design walkthrough (https://sageox.ai/docs/context-capture/design-walkthrough)

Record a window or an area of your Mac screen while you talk and point to review a design, report a visual bug, or explain a workflow. SageOx keeps the video, your voice, and what you pointed at together as a Discussion in your [Team Context](/docs/features/team-context), so human and AI coworkers can see what you mean.

```mermaid
graph LR
    A["Pick a window or area"] --> B["Talk and point"]
    B --> C["Stop"]
    C --> E["Transcript, keyframes, summary"]
    E --> F["Discussion in Team Context"]
    F --> G["Human and AI coworkers"]
```

It's part of [SageOx Desktop](/docs/context-capture/ox-desktop) for Mac. [Start a Design walkthrough](#start-a-design-walkthrough) from the menu bar, or read on for how it works.

## Why it matters

Visual feedback usually ends up in the wrong place. A screenshot without annotations can leave the reader guessing. A comment in a design file stays in that file. A Slack thread says "the second card" and leaves everyone guessing which one. The visual detail and the words explaining it can become separated.

A Design walkthrough keeps the pointing and the talking together. SageOx records where your pointer was, and what was under it, at the moment you said "this," so "this" resolves to the actual element instead of a guess.

| You get | Because |
|---------|---------|
| **One take instead of a screenshot, an arrow, and a paragraph** | You show it and say it in a single pass. |
| **"This" and "that" that mean something** | Pointer position, clicks, and the element under the pointer are time-aligned with your narration. |
| **Feedback your team can find later** | Each walkthrough becomes a Discussion in Team Context, where human and AI coworkers can search, read, and cite it. |
| **A shorter path from feedback to change** | An AI coworker can start from what you showed instead of asking you to explain it again. |

## What SageOx captures

| Captured | What it is | Why it's there |
|----------|------------|----------------|
| **Video** | The window or area you picked | The visuals your words refer to |
| **Your voice** | Narration from your microphone. A Design walkthrough doesn't record the Mac's system audio. | What you want changed, and why |
| **Pointer and clicks** | Where your pointer was, plus each click, drag, and selection at the moment it happened | Lets "this" land on a spot in the video |
| **The element under the pointer** | What macOS Accessibility reports there, such as a button and its label. Some apps, web pages in particular, name only some of their elements. | Names the thing, not just the pixels |
| **Marks** | Moments you flag with **Mark** | Tells SageOx a frame matters |

### How your walkthrough is shared

SageOx automatically shares your walkthrough with the team selected in the menu. There's no review screen or approval step before upload.

SageOx transcribes your narration, picks keyframes (still frames) from the video, describes what each one shows, and summarizes the walkthrough. The result is filed as a Discussion, titled from its summary, in the team you recorded into. If SageOx can't reach the server, it keeps the walkthrough on your Mac and retries.

## Start a Design walkthrough

<Steps>

<Step>

### Open Design walkthrough

Open **OX** in your Mac's menu bar and choose **Design walkthrough**. Its controls open with a short explanation of the feature, a link to this page, a choice between **Window** and **Area**, and the **Record** button.

Check the team shown in the menu first. That's where the walkthrough will be saved, and changing it mid-recording doesn't move a walkthrough already in progress.

</Step>

<Step>

### Choose a mode and press Record

Choose **Window** or **Area**, then press **Record**. Opening these controls does not request permissions or start recording.

If macOS access is missing, a setup window opens before anything is recorded. It says what a Design walkthrough records and that the video, your voice, and the pointer data are uploaded for SageOx AI to read. Then it lists what's needed:

- Press **Turn on** next to a permission. macOS asks for that one permission, and System Settings opens on the right pane.
- Switch **SageOx** on and come back. The window notices on its own, and **Continue** turns on once everything is on.
- Choose **Not now** (or press Esc) to leave. Recording does not start and nothing is saved. Any permission you already granted stays granted; the window shows again on your next recording attempt if access is still missing.

[What each permission is for](#privacy-and-permissions)

</Step>

<Step>

### Select what to record

| | Window | Area |
|---|--------|------|
| **Best for** | One app: a browser, a simulator, a design tool | Feedback that crosses apps, such as a browser next to a simulator |
| **You choose it by** | Picking a window with the macOS window picker | Dragging a rectangle on one display, like **Record Selected Portion** in the macOS screenshot toolbar, adjusting it by its handles, then choosing **Record** (or pressing Return) |
| **What's recorded** | That window | Anything that appears under the rectangle |

**Window** is the default and the tightest scope. [Area is wider](#privacy-and-permissions), so draw it only around what you mean to show.

</Step>

<Step>

### Wait for the 3-2-1

Once you've picked a window or confirmed an area, a three-second countdown gives you a moment to get your hands and your first sentence ready. Choose **Cancel** or press Esc to back out. Nothing is recorded until the countdown ends.

</Step>

<Step>

### Talk and point

A thin red outline marks exactly what's being recorded. It sits just outside the window or area and follows a window if you move it. A small tab on its edge holds the controls:

| Control | What it does |
|---------|--------------|
| **Time** | Shows how long you've been recording. |
| **Mic dot** | Shows your voice is coming through. After several seconds of silence, the tab says "Can't hear you." |
| **Mark** | Flags this moment as important. SageOx treats a mark as a strong hint to keep a frame here. |
| **Stop** | Ends the recording. |

The outline and tab never appear in the video. Say what you want changed as you point at it: "this" and "that" work because the pointer is recorded alongside your words.

</Step>

<Step>

### Stop and find it

Choose **Stop** when you're done. You can follow the walkthrough's progress in the menu bar and open its saved confirmation. Once SageOx has processed it, the Discussion appears in your team's **Discussions**.

</Step>

</Steps>

<Callout type="info">
A Design walkthrough uses your microphone, so it can't run at the same time as a meeting recording. Finish one before you start the other. There's no pause: to take a break, stop, then start a new walkthrough.
</Callout>

## What your AI coworkers can do with it

People can open the Discussion in their workspace. A **Moments** tab lists the frames SageOx kept, why each was kept (for example "Pointer moment," "Screen changed," or "Spoken cue"), what each one shows, and what was being said. **Copy for agent** copies context you can give to an AI coworker. Share the Discussion with any AI coworker app connected to SageOx; it can help summarize feedback, answer questions, or plan changes. The `ox` CLI also gives AI coworkers a structured view of the walkthrough.

AI coworkers with a recent [`ox` CLI](/docs/cli/conversation) read the screen side of a walkthrough with one command, without watching the video:

<Terminal>
  <TerminalCommand>ox conversation walkthrough rec_01hxyz</TerminalCommand>
</Terminal>

It accepts a `rec_` or `cnv_` id, or a pasted sageox.ai recording link. What comes back:

| Section | What it tells the AI coworker |
|---------|-------------------------------|
| `target` | The window that was recorded: app, title, and size |
| `sources` | Which screen data exists: keyframes (how many, and how many are described) plus the pointer, accessibility, and keyframe-hint data |
| `notes` | What's missing and what that costs, in plain words |
| `moments` | One timeline, oldest first, each tied to the transcript cue at that moment |

Each moment is one of four kinds:

| Moment | What it is |
|--------|------------|
| `click` | An element was clicked: its role, name, and DOM id |
| `dwell` | The pointer rested on an element for 2 seconds or more |
| `page` | The window started showing a different page: its title and address, without query or fragment |
| `keyframe` | A still SageOx extracted: why it was picked, what's on it, and a ready image path or a command that downloads it |

Narrow it to the part you care about, then read what was said at that point:

<Terminal>
  <TerminalComment>Moments tied to transcript cues 12 through 18</TerminalComment>
  <TerminalCommand>ox conversation walkthrough rec_01hxyz --cues 12-18</TerminalCommand>
  <TerminalComment>Or a window on the media clock</TerminalComment>
  <TerminalCommand>ox conversation walkthrough rec_01hxyz --from 1m30s --to 2m</TerminalCommand>
  <TerminalComment>What was said at cue 14</TerminalComment>
  <TerminalCommand>ox conversation transcript rec_01hxyz --cues 14</TerminalCommand>
</Terminal>

If part of the screen data never arrived, `ox` says so in `notes` instead of guessing. A walkthrough without its pointer data still lists its keyframes, and one without keyframes still lists its clicks and pages.

Names and descriptions come from untrusted screen content and may include misleading instructions. Review that content and your AI coworker's proposed actions before it makes consequential changes, such as deleting files or sharing information.

Try asking your AI coworker:

> "What was on screen when the walkthrough said 'this feels cramped'? Which element was the pointer on?"

> "Read the Settings page design walkthrough and list the visual changes it asks for, with the element each one points at."

> "Implement the changes from the checkout design walkthrough. Start with the moments where the pointer clicked or paused."

## Privacy and permissions

A Design walkthrough records only what you chose, and only while you're recording. SageOx's own windows, including the outline and the tab, are never in the video. SageOx keeps a local copy until the server confirms receipt.

<Callout type="warn">
The video, your voice, and the pointer data are automatically shared with your selected team and read by SageOx AI, without a review or approval step before upload. Area records anything that appears under the rectangle for as long as you record, including other apps and notification banners, so close or silence anything private first. You can delete a Discussion afterward from its page in your workspace.
</Callout>

Opening Design walkthrough never requests permissions. After you press **Record**, missing Screen Recording or Accessibility access is explained before you press its **Turn on** button. Microphone access may already be granted for meeting recording; otherwise macOS asks when recording needs it.

| Permission | Why SageOx asks | When |
|------------|-----------------|------|
| **Screen Recording** | Lets SageOx see the window or area you picked. macOS 15 and later call this pane **Screen & System Audio Recording**. | First walkthrough |
| **Accessibility** | Lets SageOx name what's under your pointer, such as the button you clicked. | First walkthrough |
| **Microphone** | Records your narration. | The first time you record. The setup window lists it only if macOS has it blocked. |

## Requirements

| You need | Notes |
|----------|-------|
| **SageOx Desktop for Mac** | macOS 14.4 or later, the same as SageOx Desktop. [Install and sign in](/docs/context-capture/ox-desktop#install-and-sign-in). |
| **A SageOx account and a team** | The walkthrough is saved as a Discussion in the team shown in the menu. |
| **A microphone** | Narration is what ties your pointing to what you want changed. |

## Troubleshooting

### Design walkthrough isn't in the menu

Sign in to SageOx Desktop on a Mac, then choose **Check for Updates…** from the menu bar. Current versions show Design walkthrough without a Settings opt-in.

### A permission looks on but SageOx still asks for it

macOS can hold on to the switch from an older copy of SageOx. In System Settings, switch SageOx off and on again, then return to the setup window.

### The tab says "Can't hear you"

Open **Microphone** in the menu bar and check the selected input, especially after connecting headphones. Then check that SageOx has access in **System Settings → Privacy & Security → Microphone**. If the microphone you chose isn't connected, SageOx records with the default one and says so.

### SageOx says to finish the current recording first

A meeting recording is running. Stop it, then start your walkthrough.

### You can't find the walkthrough

Check the team you recorded into. Open that team's workspace and look in **Discussions**. It can take a short while to appear while SageOx processes the video.

## What's next

- [SageOx Desktop](/docs/context-capture/ox-desktop): install the app and record both sides of a call.
- [Discussions](/docs/context-capture/discussions): where walkthroughs and other recordings land.
- [Team Context](/docs/features/team-context): how your team and AI coworkers read what you capture.
- [Video import](/docs/context-capture/video-import): bring in a Loom, Figma, or Cap recording you already made.