Running into this?

If you talk to your agent a lot

Situations I ran into and solved while telling my agents things all day. Find yours, hand the decision to your agent.

I grab the screen with ⌥⇧S and box the spots to look at; each box gets a number, and I tell the agent by number.
before0 boxes on the image · the spot spelled out in words as “top right”
after1,020 numbered marks on 496 images in 7 days, 939 of them boxes
don't describe in words where to look in a screenshot; draw numbered boxes on the image and refer to them by number
Text for your agent · 16 lines
Situation: the person pastes a screenshot to you and describes in words where to look (“the button at the top right”, “the second row”). You ask “which one?” or change some other spot that also fits the description.

Why: the image reaches you as pixels; a written description like “top right” doesn't bind to one place in the image. A numbered box drawn on top of the image is part of the image: “the button in 1” points to exactly one place. In 7 days I drew 1,020 numbered marks on 496 images, 939 of them boxes.

Do:
1. Have the person install OptionOS (macOS): open the OptionOS disk image (.dmg) downloaded from https://optionos.app/download and double-click OptionOS in the window that opens: it installs itself into Applications and opens.
2. On first launch OptionOS first asks them to accept the terms and answer a few questions, then lists a few permissions on its permissions page. This job needs two: Screen Recording (System Settings calls it “Screen & System Audio Recording”) and Accessibility (called “Device Control and Data Access” on macOS 27). Have the person turn both on for OptionOS in System Settings › Privacy & Security; you can't grant them. No image is taken without permission: while one is missing, ⌥⇧S shows a “PERMISSION MISSING” card next to the pointer with the missing permission's name; if the person sees that card, the permission isn't on. If the setup questions ask about screenshots, answering “No” only hides the ⌥⇧S intro card; the shortcut still works.
3. Show the person: ⌥⇧S (Option + Shift + S) freezes the screen. Clicking a window takes that window, dragging takes that area (Esc cancels). The image opens in the editor; they draw a rectangle on every spot to look at (Rectangle is the tool selected on open): a number appears at each box's corner (1, 2, 3 …), in the box's color, red by default. Arrow, Line and Text marks get numbers too. A deleted mark's number isn't reused: delete 2, draw a new box, and the numbers are 1, 3. They press Done (⌘↩ does too): the image is copied to the clipboard with its boxes. In the editor, Esc or the window's red button is not Done: the boxes drawn are thrown away and nothing goes to the clipboard.
4. They paste the image to you and refer to it by number: “the label on the button in 1 is wrong, the row in 2 overflows”. Use the same number in your reply.
5. The same menu sits in the OptionOS menu bar under “Show what's on screen”: a person who forgets the shortcut picks “Screenshot + Annotate” there.

Verify (after the person presses Done and pastes the image to you):
- in the pasted image you see a number inside a filled circle at the corner of every mark (the Counter tool's mark carries its number inside its own circle, not at a corner); no numbers at all means no mark was drawn or the image came from another tool: go back to step 3 · if a file path arrived instead of an image (in a terminal ⌘V pastes the clipboard image as its path; the path looks like …/app.optionos.screencapture/annotation/<id>/rasters/<time>.png): open that file, it is the boxed image; don't count it as an unnumbered image and go back to step 3 · if what got pasted isn't this image (whatever was on the clipboard before): the person closed the editor with Esc instead of Done, or “Copy every screenshot to the clipboard” is off in OptionOS settings: go back to step 3
- right after Done, without taking another image in between, run on the person's Mac: A="$HOME/Library/Application Support/app.optionos.screencapture/annotation"; f=$(find "$A" -maxdepth 2 -name context.json -exec /usr/bin/stat -f '%Fm %N' {} + | sort -rn | head -1 | cut -d' ' -f2-); plutil -extract annotations json -o - "$f" | grep -o '"sequence":[0-9]*' → one line per mark drawn on the latest image ("sequence":1, "sequence":2 …; a deleted mark's number is skipped, so 1 and 3 is not incomplete) · empty output: the most recent image has no marks (if an unmarked image was taken after Done, that one is the latest · if the person pressed Esc instead of Done, the boxes they drew never entered the record) · “Empty path specified” (possibly preceded by “No such file or directory”): no image has ever been taken on this Mac, go back to the permissions in step 2

Don't: when the person's image has no numbers, don't try to find the spot by guessing anyway; ask them to take it again with boxes. Don't draw the boxes yourself: a box means the spot the person wants looked at, and only the person knows it. Don't find the latest record for Verify with `ls -t "$A"/*/context.json`: once there are thousands of records (each image is a folder) the shell prints “argument list too long”, and a full Mac shows “Empty path specified” as if no image had ever been taken.
I talk to my agents through OptionOS's Speak: every text and image I copy while talking piles up in the card next to my cursor, so I see what I copied; all of it lands inside the sentence I was saying when I copied it, marked and in order. I don't paste copies and images into the agent one by one; ⌥V writes the finished talk in one go.
before1,464 copies in 7 days, each one a separate window switch and paste
after0 pasted copies · every copy inside the sentence it was said in
Install OptionOS, press ⌥A to talk, copy with ⌘C while you talk, press ⌥A to finish, press ⌥V to write it into the chat
Text for your agent · 37 lines
Situation: the person talks to an agent (Claude Code · Codex · ChatGPT) at length, by voice or by typing, and while talking keeps copying a line, an error message or a link from another window and pasting it into the chat. The pasted copies pile up at the end of the message, which copy belongs to which sentence gets lost, and the person wears out from talking plus copy-pasting.

Why: the clipboard holds one copy, and nothing ties a copy to the sentence being said: every copy costs a separate window switch and paste, and the order lives in the person's memory. In 7 days I had 1,464 text copies across 2,374 dictations; OptionOS's Speak ties each copy to the moment it was said, and I pasted none of them by hand.

Do:
1. First check whether OptionOS is already installed:
   ls -d /Applications/OptionOS.app ~/Applications/OptionOS.app
   Every path printed is an installed copy; if one of the paths is missing the command prints "No such file or directory" and exits with 1, which does not mean "not installed": look at the printed line. If a copy exists, don't install and don't copy over it (copying over an old copy mixes two versions and breaks the signature); note that path as "the app's path", open it with open -a <the app's path> (if it is already running nothing changes) and go to step 6. If both paths are printed, note both; the second Verify line shows which one is running.
2. Ask the person: OptionOS is a paid Mac app. Show them the price on https://optionos.app/pricing: there is a discounted first-month offer (the end date is on the page), then $24.90 a month (excluding tax), renewing automatically until they cancel; there are also 6- and 12-month plans. Don't download without their approval.
3. Download and mount the disk image at a fixed place:
   curl -fL -o /tmp/OptionOS.dmg https://optionos.app/download
   hdiutil attach -nobrowse -readonly -mountpoint /tmp/OptionOS-dmg /tmp/OptionOS.dmg
   (On newer macOS hdiutil may print a "deprecated" warning here and in step 5, and "CRC32" lines here; these are not errors, step 4 shows whether the disk is mounted.)
4. Check the signature; if you don't see "accepted" and "source=Notarized Developer ID", don't install:
   /usr/sbin/spctl -a -vv /tmp/OptionOS-dmg/OptionOS.app
   "invalid API object reference" means there is no app at that path: run step 3 again from the start.
5. Copy it into Applications, eject the disk, delete the download, open it; the app's path is now /Applications/OptionOS.app:
   ditto /tmp/OptionOS-dmg/OptionOS.app /Applications/OptionOS.app
   hdiutil detach /tmp/OptionOS-dmg
   rm /tmp/OptionOS.dmg
   open -a /Applications/OptionOS.app
   If ditto prints "Permission denied", the account can't write to /Applications: run the ditto and open lines with ~/Applications instead of /Applications (ditto creates the folder if it is missing; if ditto prints "Cannot get the real path for source", run step 3 again from the start first); the app's path becomes ~/Applications/OptionOS.app.
   Tell the person: the setup window that opens asks for permissions one by one; without the Microphone permission speech doesn't turn into text. The person grants the permissions themselves; you can't.
6. Show the person the first use, and do it together once:
   - Click the agent's chat box.
   - Press ⌥A once: recording starts. Start talking.
   - While talking, select a line in another window, copy it with ⌘C, keep talking.
   - Press ⌥A again: recording stops and the text waits in the card next to the cursor; it hasn't been written anywhere yet.
   - Click back into the agent's chat box (another window came to the front while you copied) and press ⌥V: the text lands at the cursor of the frontmost window. ⌥⇧V writes and sends.
   - If you copied the wrong thing, ⌥⇧Z undoes the last copy while recording. ⌥⎋ throws away the dictation while recording, and after recording the text waiting in the card, without writing anything.

Verify:
- Only if you installed in step 5: /usr/sbin/spctl -a -vv /Applications/OptionOS.app (if you installed to ~/Applications: /usr/sbin/spctl -a -vv ~/Applications/OptionOS.app) → "accepted" and "source=Notarized Developer ID". On any other output, whatever the message, delete the OptionOS.app you installed and reinstall from step 3. Don't judge a copy that was already installed with this line: developer builds print "rejected · source=Unnotarized Developer ID" but are sound.
- /usr/sbin/lsof -a -c dictation-r -d txt -Fn | grep '/MacOS/dictation-runtime$' | sed 's#/Contents/.*##' | sort -u → a single line: the letter "n" followed by the app's path (the one you noted in step 1 or installed in step 5; ~ is spelled out here as /Users/<name>). No line means Speak hasn't opened; more than one line or a different path means another copy is running.
- In the text that reaches the person's agent after ⌥V in step 6: there is an `O1` mark where the copy was made, and below the text an attachment line carries the same id (`<optionos-attachment id="O1" … href="…">`). Before ⌥V the chat box is empty; the text is waiting in the card. In a terminal agent (Claude Code · Codex) the attachment line points to the file where the copy is stored, and the agent opens and reads it. If you talk to claude.ai, ChatGPT or Gemini in the browser, the attachment line carries no file path: every text or image you copied arrives attached to the message as its own file, and the chat reads it like a file you dragged in. The person sees this; if you can't see the screen, ask them.

Don't: write your own clipboard watcher or script to merge the copies; and don't try to turn on the person's permissions (like Microphone) with a command: macOS doesn't allow it, the person turns them on in the setup window or in System Settings.
I talk to my agents through OptionOS's Speak with «Send When the Agent Is Done» on: what I say while the agent is working is written into the chat box but not sent, and waits in the card with ⏱; whatever I say next piles up next to it. When the agent's turn ends, Enter is pressed on its own and it all goes as one message.
beforeClaude Code's queue: the second message cut in after step 2 of a 3-step task
aftertoday 18 messages held until the agent was done · 17 went when the turn ended · 0 left behind after a turn ended
Install OptionOS, keep Speak › Send When the Agent Is Done on, press ⌥A to talk while the agent works, ⌥A to finish, then ⌥⇧V: it goes when the agent is done
Text for your agent · 36 lines
Situation: the person gave an agent a task in Claude Code, thinks of something else while the agent is working, and types and sends it. Claude Code shows the message as «queued»; the person assumes it will go when the task is done, but it reaches the agent in the middle of the task: the agent leaves the half-done work to answer the new message, then goes back to the main task or doesn't.

Why: Claude Code's queue hands the message to the agent not when the agent's turn ends but as soon as the tool calls running right now finish, inside the same turn. In my setup (Claude Code 2.1.325) I gave the agent three separate 20-second commands and sent a second message at second 30: it reached the agent after the 2nd command, the agent answered it, and only then ran the 3rd command. anthropics/claude-code#50246 tracks this as an open request. OptionOS's Agents part looks at the turn state in Claude Code's session record and presses Speak's Enter when the agent's turn ends. On 16 November 2026, 18 messages of mine waited this way: 17 went when the turn ended, and I took 1 back myself before the turn ended.
This only works in Claude Code and only for what you send by talking through OptionOS: it doesn't touch a message you type and send with Enter yourself, and Codex or a chat in the browser doesn't publish its turn state, so there Enter is pressed right away.

Do:
1. First check whether OptionOS is already installed:
   ls -d /Applications/OptionOS.app ~/Applications/OptionOS.app
   Every path printed is an installed copy; if one of the paths is missing the command prints "No such file or directory" and exits with 1, which does not mean "not installed": look at the printed line. If a copy exists, don't install and don't copy over it (copying over an old copy mixes two versions and breaks the signature); note that path as "the app's path", open it with open -a <the app's path> (if it is already running nothing changes) and go to step 6.
2. Ask the person: OptionOS is a paid Mac app. Show them the price on https://optionos.app/pricing: there is a discounted first-month offer (the end date is on the page), then $24.90 a month (excluding tax), renewing automatically until they cancel; there are also 6- and 12-month plans. Don't download without their approval.
3. Download and mount the disk image at a fixed place:
   curl -fL -o /tmp/OptionOS.dmg https://optionos.app/download
   hdiutil attach -nobrowse -readonly -mountpoint /tmp/OptionOS-dmg /tmp/OptionOS.dmg
   (On newer macOS hdiutil may print a "deprecated" warning here and in step 5, and "CRC32" lines here; these are not errors, step 4 shows whether the disk is mounted.)
4. Check the signature; if you don't see "accepted" and "source=Notarized Developer ID", don't install:
   /usr/sbin/spctl -a -vv /tmp/OptionOS-dmg/OptionOS.app
   "invalid API object reference" means there is no app at that path: run step 3 again from the start.
5. Copy it into Applications, eject the disk, delete the download, open it; the app's path is now /Applications/OptionOS.app:
   ditto /tmp/OptionOS-dmg/OptionOS.app /Applications/OptionOS.app
   hdiutil detach /tmp/OptionOS-dmg
   rm /tmp/OptionOS.dmg
   open -a /Applications/OptionOS.app
   If ditto prints "Permission denied", the account can't write to /Applications: run the ditto and open lines with ~/Applications instead of /Applications (ditto creates the folder if it is missing; if ditto prints "Cannot get the real path for source", run step 3 again from the start first); the app's path becomes ~/Applications/OptionOS.app.
   Tell the person: the setup window that opens asks for permissions one by one; without the Microphone permission speech doesn't turn into text. The person grants the permissions themselves; you can't.
6. Ask the person (you can't see the menu): in the menu bar, does OptionOS › Speak show a ✓ next to «Send When the Agent Is Done»; if not, they click the row once.
7. Show the person the first use, and do it together once:
   - Give Claude Code a task that takes more than a minute (for example «run perl -e 'select(undef,undef,undef,20)' three times as three separate Bash calls, one after another, in the foreground without sending them to the background, then write DONE») and click the chat box while the agent works.
   - Press ⌥A once, say your second request, press ⌥A again: recording stops and the text waits in the card next to the cursor.
   - Press ⌥⇧V: the text lands in the chat box but isn't sent, and ⏱ shows on the card.
   - If you like, talk once more and press ⌥⇧V: the new words pile up next to the earlier ones.
   - When the agent writes DONE, Enter is pressed on its own and what piled up goes as one message.

Verify:
- In step 7, after ⌥⇧V the text stays in the chat box until the agent writes DONE, then goes on its own. The person sees this; if you can't see the screen, ask them.

Don't: send the message into Claude Code's own queue with Enter while the agent works and assume it will go when the task is done; and don't press Enter yourself on words that should wait: OptionOS presses Enter when the agent's turn ends.