Macrophone

Docs

When an agent needs you

An agent that stops to ask a question used to wait until you walked back to your desk. Now your iPhone tells you, and answering is a tap.

The alert#

When an agent on your Mac asks something and nobody is watching its window, your iPhone gets a notification: “Claude Code is asking you something”, with the window and the question. Tap it and that window opens on your phone with its answers as buttons. One alert per question; you don't get one for a window you're already looking at.

It's on in Settings › Tell me when an agent asks something, and your iPhone asks for notification permission the first time you watch a window.

Connecting Claude Code and Codex#

Claude Code and Codex can tell Macrophone themselves when they start working, ask you something, finish or close, so your iPhone knows exactly which one is waiting, with no false alarms. In the Mac app, open Agents and choose Connect next to each. (Until you do, the menu bar offers Connect Claude Code….)

What Connect does, so you can check it:

  • Claude Code: adds …/Macrophone.app/Contents/Helpers/macrophone hook claude to the hooks in ~/.claude/settings.json (SessionStart, UserPromptSubmit, PermissionRequest, Notification, PostToolUse, Stop and SessionEnd).
  • Codex: sets notify in ~/.codex/config.toml to macrophone hook codex. If you already run something there, Macrophone leaves it alone and says so.
  • The first change backs the file up beside it (.macrophone-backup). Disconnect takes out exactly what it added.
  • The hook posts each event to Macrophone's local API on your Mac. It prints nothing, never fails your session, and gives up after 1.5 seconds. The Local API needs to be on (it is, unless you turned it off in Developer).

It takes effect for sessions started after you connect. A connected agent's window is left alone by the window reading below, so you're never told twice.

Any other app#

For an agent that isn't connected (Gemini CLI, Aider, anything in a terminal, Cursor, the Claude app), your Mac looks at the agent windows nobody is watching every five seconds while your iPhone is connected, and reads a question off any that shows one: a numbered menu with a highlighted answer, a (y/n), or in the Claude app a question card or an Allow/Deny row. It reads only the part of the window you type in, never a sidebar, and tells your iPhone once per question. An unchanged window isn't read again, so it costs the Mac next to nothing.

While the iPhone app is closed#

While Macrophone is open on your iPhone, the alert comes straight from your Mac over the same encrypted connection as everything else. When the iPhone app is closed, your Mac leaves a note in your own iCloud account instead: the app and the window's name, never the question. iOS wakes your phone with it, and a tap opens that window. This needs iCloud signed in on both and notifications allowed; nothing goes through a server of ours.

A chat that answered you#

A window becomes a chat when you send a dictation there, or answer it or press Return in it from your phone. When its agent answers, its app's icon in Send to wears a small ember dot, the name reads Answered you (or Asking you), and the window menus mark it. Tap the dot to open the window that answered; looking at it on the phone clears the mark.

For a connected agent the mark is exact. For any other chat, your Mac notices new content and then stillness, and never calls it answered while the window still says it's working: a Stop button in the Claude app or ChatGPT, “esc to interrupt” in a terminal.

For scripts#

The same events are a POST /v1/agent on the local API, so any agent or script on your Mac can tell Macrophone it's waiting on you.