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
- 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.
- 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.
- Apple's command line tools, for
python3andclang. Ifxcode-select -pprints 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. This is the checklist.
-
Free the Globe key. System Settings, Keyboard: Press 🌐 key to, Do Nothing. Then switch off Dictation. Tapping Globe should now do nothing.
-
Install Superwhisper with a local model, and record one short test. That creates the folder the watcher reads.
-
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 SessionShift+Globe off DictateGlobe 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.
-
Move screenshots off the Desktop, which the watcher can't read:
mkdir -p ~/Pictures/Screenshots defaults write com.apple.screencapture location ~/Pictures/Screenshots killall SystemUIServer -
Download the installer, read it, run it. It's safe to run again to update.
curl -fsSL https://intelligenceintelligence.io/skills/voice-notes/install.sh -o install.sh less install.sh sh install.sh -
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.
launchctl kickstart -k gui/$(id -u)/dev.solarise.voice-note -
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:
# 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` 
`+4s` “The second column drops below the first.”
`+5s` 
</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:
{
"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
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:
- Which projects should notes be routed to, if any?
- Does anyone else use this Mac?
- 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. failedcounting 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.
- 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.
- 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
--sessionon the handled one too. If the chat runs from a parent folder, set--projectto the project you're actually working on. - Open only the frames you need. In
note.mdeach 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. - 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.
- 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.