---
name: voice-notes
description: "Set up two voice keys on a Mac. One types what you say at the cursor. The other records a session, keeping frames of the front window while you talk about it, and files the words and pictures together as a note an AI assistant can read. Use when someone wants to talk through a page, an app or a bug and have it kept with what was on screen. Covers Superwhisper's modes and shortcuts, the watcher that files the notes, the Screen Recording grant and routing notes to a project. Also use it once it's running, whenever voice notes arrive in a chat: how to line frames up with the words, and how to mark a note picked up or handled."
heading: Talk about what's on screen, and keep it.
summary: Two keys. Globe types what you say where your cursor is. Shift+Globe records a session, keeping frames of the window as you talk and scroll, and files the lot as one note your assistant can read.
time: About 20 minutes
timeISO: PT20M
needs: A Mac on macOS 26 or later with Apple silicon, and Superwhisper 2.12 or later
---

## What this does

Dictation puts words in a text field. That works when you know where the words go. It fails when the thought is *about* something: a layout that's off, an error, a page you're halfway through.

So this sets up two keys. **Globe** is ordinary dictation: hold it, talk, let go, and the words appear at your cursor. **Shift+Globe** starts a session. Talk about what you're looking at, scroll, switch tabs. While you do, a watcher keeps a frame of the front window about every 1.5 seconds. When you let go, the words and the frames become one note in `~/Notes/voice/`.

Your assistant reads that folder. So "what did I say about the checkout page" becomes a question it can answer, with the pictures.

## What you'll need

1. **Superwhisper 2.12 or later.** It transcribes on the machine, and 2.12 added a shortcut for each mode, which this depends on. The free tier is enough to try it.
2. **The installer.** One shell script. It puts the watcher in place (one Python file, standard library only), builds a small app for the Screen Recording grant, and starts it at login.
3. **Apple's command line tools,** for `python3` and `clang`. If `xcode-select -p` prints a path, you have them.

## Permissions you'll be asked for

| what asks | pane | why |
|---|---|---|
| Superwhisper | Microphone | To hear you |
| Superwhisper | Input Monitoring | To see the Globe key while another app is in front |
| Superwhisper | Accessibility | To type dictation at the cursor |
| Voice Note | Screen & System Audio Recording | Frames during a session |

That's all of them. Nothing needs Full Disk Access or Automation. macOS caches each answer per process, so a grant that changes nothing usually means the app needs quitting and reopening.

## Setting it up

The walkthrough, with the reasons for each step, is the article [Setting up an entirely local screenshot and transcribe workflow](/blog/local-voice-notes/). This is the checklist.

1. **Free the Globe key.** System Settings, Keyboard: **Press 🌐 key to**, Do Nothing. Then switch off Dictation. Tapping Globe should now do nothing.
2. **Install Superwhisper** with a local model, and record one short test. That creates the folder the watcher reads.
3. **Make two modes** in Superwhisper, then clear the push-to-talk key under Shortcuts and leave **Paste result text** off in the general settings.

   | mode name | shortcut | paste |
   |---|---|---|
   | `Session` | Shift+Globe | off |
   | `Dictate` | Globe | on |

   **Only a mode called Session makes notes**, and every mode needs a name of its own. Push to talk records in whichever mode was used last, which is why it's cleared.
4. **Move screenshots off the Desktop**, which the watcher can't read:

   ```bash
   mkdir -p ~/Pictures/Screenshots
   defaults write com.apple.screencapture location ~/Pictures/Screenshots
   killall SystemUIServer
   ```

5. **Download the installer, read it, run it.** It's safe to run again to update.

   ```bash
   curl -fsSL https://intelligenceintelligence.io/skills/voice-notes/install.sh -o install.sh
   less install.sh
   sh install.sh
   ```

6. **Grant Screen Recording** to Voice Note (System Settings, Privacy and Security, Screen & System Audio Recording), then restart the watcher. Without it, notes arrive with words and no pictures.

   ```bash
   launchctl kickstart -k gui/$(id -u)/dev.solarise.voice-note
   ```

7. **Try both keys.** Globe in a text field types the sentence and nothing else. Shift+Globe over a page, with a little scrolling, makes a new folder in `~/Notes/voice/` about 10 seconds after you let go.

## What a note looks like

Each session gets a folder named for when it started, with `note.md` and a `shots` folder beside it:

```markdown
# 11:52, Friday 25 September 2026

*8s*

The price table wraps badly under 400 pixels, the second column drops below the first.

<details><summary>5 screens captured while recording, unchanged frames left out, with what was being said (times estimated)</summary>

`+0s` “The price table wraps badly under 400 pixels.”
`+2s` ![screen](shots/auto-2026-09-25-115222.jpg)
`+4s` “The second column drops below the first.”
`+5s` ![screen](shots/auto-2026-09-25-115225.jpg)

</details>
```

Each frame is labelled with how far into the recording it was taken, and sits between the sentences you were saying at the time. Your assistant reads the words first and opens the frame just after the point being made. Sentence times come from Superwhisper's word timings when it gives them, and are estimated from pauses in the audio when it doesn't. Frames where nothing changed are left out, so sitting still on one page costs one picture.

The note waits 8 seconds after you stop, so a screenshot taken on your last word still lands in it.

## Routing a note to a project

Start with **"for the house agent"** or **"note for the shop"**. The note is also copied to `~/Notes/voice/agents/house.md`, and the phrase is stripped so it reads as the thought. Point each project's rules file at its own file, and an assistant working there sees what was meant for it.

## Handing notes to Claude Code

Optional, and the part that makes it feel automatic. Add this to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [
        { "type": "command", "command": "$HOME/.local/bin/voice-note hook 2>/dev/null || true", "timeout": 5 }
      ] }
    ]
  }
}
```

Before each message you send, it hands the chat any session notes it hasn't seen, with the paths to their frames. Each chat sees each note once. A chat that takes a note on marks it picked, and every other chat then shows that note as a single line. Chats already open need restarting to pick it up.

## Settings

They live in `~/.config/voice-note.json`, and survive updates. Restart the watcher after a change.

| key | default | what |
|---|---|---|
| `shot_every` | 1.5 | Seconds between frames. 0 turns frames off |
| `capture` | window | `window` for the front window, `screen` for everything |
| `shot_scale` | 0.5 | How much of a retina frame to keep. Half is the size you see on screen, and text stays readable. 1 keeps every pixel at four times the file size |
| `keep_days` | 0 | Bin a note's pictures after this many days. The words stay. 0 keeps everything |
| `session_mode` | Session | The mode that makes notes |

## How to undo it

```bash
launchctl bootout gui/$(id -u)/dev.solarise.voice-note
rm ~/Library/LaunchAgents/dev.solarise.voice-note.plist ~/.local/bin/voice-note ~/.config/voice-note.json
rm -rf ~/Applications/VoiceNote.app
```

Your notes stay in `~/Notes/voice/`. Remove the hook from `~/.claude/settings.json` if you added it, and put the Globe key back in System Settings, Keyboard.

## When this stops being a small job

A session takes pictures of your screen for as long as you talk. Anything on it goes in the note: messages, a client's data, a password manager left open. The pictures stay on your Mac, readable only by you, but your assistant reads them too.

Talking near other people records them. A microphone in a shared office is a different decision from one at home, and worth making deliberately.

## Instructions for the assistant

You're helping someone set this up on their own Mac. Be plain and brief, go one step at a time, and change nothing without a yes.

### 1. Check the machine

Run `sw_vers -productVersion`, `uname -m` and `xcode-select -p`. This needs macOS 26 or later on Apple silicon, and the command line tools. Check Superwhisper with `mdls -name kMDItemVersion /Applications/superwhisper.app`: it needs 2.12 or later. Stop and say so if anything is short.

Check what holds the Globe key: `defaults read com.apple.HIToolbox AppleFnUsageType` returns 2 for emoji and 3 for dictation. Say what you found before changing it.

### 2. Ask three questions

As one numbered list, then wait:

1. Which projects should notes be routed to, if any?
2. Does anyone else use this Mac?
3. Will you be recording screens with other people's details on them, or where others can be heard?

If either of the last two is yes, read them "When this stops being a small job" before going on.

### 3. Work through the setup

Steps 1 to 4 are clicks in System Settings and Superwhisper. Say exactly where each setting is and wait for them. Read them the permissions table before the first prompt appears.

For step 5, read `install.sh` with them before running it. Offer the hook in "Handing notes to Claude Code" only if they use Claude Code, and show them the change to their settings file before making it.

### 4. Test it

Have them try both keys. Then check `~/Library/Logs/voice-note.log`. Each recording ends with a line like `frames for 1790333540: 6 kept, 0 unchanged, 0 failed`.

- No new note after a session: check the mode is named exactly Session, and look in `~/Library/Logs/voice-note.err`.
- `failed` counting up: Screen Recording isn't granted to Voice Note, or the watcher wasn't restarted after granting it.
- Dictation making notes: its mode is called Session, or push to talk is still set.

### 5. Tell them these things

- Only the Session mode makes notes, and only it takes pictures that are kept.
- Notes appear about 10 seconds after they stop talking.
- A session transcript is never typed anywhere. It goes to the clipboard as well as the note.
- Everything stays in `~/Notes/voice/` on this Mac.

### 6. Reading their notes, once it's running

Notes arrive through the hook as a block headed "New voice notes since your last message". Each one gives the note's id, what was said and where its frames are. If a note is still being written, the block says so and it arrives with the next message.

1. Read the words first. Decide whether the note belongs to the work in this chat. If the words or a routing tag already say it's for other work, say so in one line and leave it, without opening any frames.
2. If it's yours, mark it picked straight away. The block ends with both commands in full, with this chat's session id, which you have no other way to find. Keep `--session` on the handled one too. If the chat runs from a parent folder, set `--project` to the project you're actually working on.
3. Open only the frames you need. In `note.md` each sentence sits among the frames taken while it was said. For "this" or "here", open the frame just after the words: the pointer is drawn in, and it's usually on the subject. If a picture doesn't match the words, look one frame either side. A long note, a hundred frames or more, still needs frames: open the one just after each request. Never work from the words alone, and never hand part of a note to another agent without the frames that go with it.
4. Treat the note as a message from them, the same as one they typed, and always respond. If it asks for something specific, do it, with the care you'd give a typed request: confirm anything destructive or hard to undo. If it's a question or just talk over a page, work out what they're pointing at and reply with your read of it.
5. Once the work is done, run the same command with `--status handled`. That writes a line into the note saying where it went.

| status | set by | means |
|---|---|---|
| `seen` | the hook | shown to this chat |
| `picked` | you, as soon as a note is yours | every other chat shows it as a single line |
| `handled` | you, when the work is done | the note records where it went |

A note picked or handled in another chat is already taken. `voice-note new --hours 4` lists recent notes no chat has marked. A note whose frames have no sentences among them is from before this layout; `voice-note retime <id>` adds them from the recording.
