The short answer
There are two ways to get your phone to buzz when Claude Code or Codex finishes, fails or stops to ask for permission. You can wire it up yourself with Claude Code hooks or Codex's notify setting and forward events to ntfy, Pushover or a Telegram bot. Or you can use an app that runs on your computer, such as BotBus, which pushes to your iPhone, Apple Watch or Android phone whenever a task starts waiting for approval, waiting for an answer, completes or fails, and opens that task when you tap the notification so you can approve, answer or follow up. The DIY route is free and flexible and is often all you need. Where it stops is that it can only tell you something happened, and you have to think about whose servers your notification text passes through.
Why notifications matter more than they sound
Long agent runs rarely go straight through. Claude Code stops to ask before running a shell command or touching files outside the project. Codex stops for approvals too. When the turn ends, both just sit quietly in the terminal. So you either babysit the screen or check back every so often, and the usual experience is coming back to find the agent stopped ten minutes ago and has been waiting on you ever since.
A useful notification setup does two things: it tells you the moment it's your turn, and ideally it lets you act on it right there. The first part is the push. The second part is whatever opens when you tap it.
The DIY route: hooks and notify
This works, and plenty of people stop here. The details below were checked against the official Claude Code and Codex docs on 2026-10-06.
Claude Code hooks
Claude Code's Notification hook fires whenever Claude Code wants your attention, and you can match on notification_type: permission_prompt when a permission dialog appears, idle_prompt when a turn has ended and the prompt has been sitting idle, agent_needs_input, and a few others. The Stop hook fires when Claude finishes a response. Point those two events at a command or an HTTP endpoint in ~/.claude/settings.json, forward to ntfy, Pushover, Bark or a Telegram bot, and your phone rings.
The catch is spelled out in the docs: the Notification hook is observe-only. Its exit code and output are ignored, so it can't make a decision. Your phone will tell you Claude Code wants approval, but to grant it you still walk back to the computer, unless you build a second piece that sends answers back.
Codex notify
Codex has a notify key in config.toml, for example notify = ["python3", "/path/to/notify.py"]. Your program receives one JSON argument with the thread id, working directory, the input messages and the last assistant message. Right now the only event it fires for is agent-turn-complete. Approval requests do not trigger notify. The terminal UI's built-in tui.notifications can raise a desktop notification on approval-requested, but that's a local desktop notification, which doesn't help when you're not at the desk. Codex also supports lifecycle hooks; covering approvals with those is something you configure and test yourself.
Where the DIY route runs out
- It notifies, it doesn't act. "Waiting for approval" arrives on your phone, and there's nothing to tap that actually approves.
- Coverage is patchwork. Codex's
notifyonly knows "turn complete". Failures, a macOS permission dialog blocking the agent, or a question asked mid-conversation each need their own handling. - One setup per agent, per machine. Running both Claude Code and Codex means two configs and two scripts. A second computer means doing it again.
- Your text goes somewhere. Notification bodies tend to include commands, file paths and the agent's last reply. With a public push service, that usually travels in plain text through their servers. Self-hosting fixes it but gives you one more thing to run.
If you use one agent and just want to know when it's done, a short script is the right answer. You don't need to install anything else for that.
How BotBus does it
BotBus runs on your computer (a menu bar app on Mac, a background CLI on Linux), discovers local agents like Codex, Claude Code, Hermes, Pi, OpenClaw and DeepSeek Harness, and syncs their tasks to your phone and watch. Push notifications come with that, and the rules are fixed.
When your phone buzzes
A task triggers one push when it enters one of four states:
| State | Title names | Body shows |
|---|---|---|
| Waiting for approval | the agent and the state | what it wants to do |
| Waiting for your answer | the agent and the state | the question it asked |
| Completed | the agent and the state | the last reply |
| Failed | the agent and the state | the last message or error |
Running tasks and tasks you interrupted yourself don't notify. The same task in the same state with the same request notifies at most once every 30 seconds, so nothing spams you. When BotBus starts it records the current state silently first, so restarting your computer doesn't dump a backlog of "completed" pushes on you. Projects you've removed from the list stop notifying too.
This isn't limited to tasks started from your phone. Codex sessions from your terminal or the desktop app notify as well, as long as BotBus can see their state change. For Claude Code terminal sessions, click "Install hooks" under Local Agents in BotBus settings first. BotBus learns about permission requests, finished turns and failures through those hooks, and the installer only merges its own entries, leaving your existing hooks in place.
Two cases are specific to the Mac version. If a task fails because a macOS permission dialog blocked it, you get a push saying the computer needs a system permission. If an agent stops for input while a password field happens to be focused on the Mac, the notification tells you that you can operate the computer from your phone to fill it in.
What you can do after tapping it
Tapping the notification opens that task with the full request or conversation. From there you can:
- Approve or deny a permission request, or tap one of the options when the agent asks a multiple-choice question.
- Send a follow-up once it's done, or read why it failed and decide whether to retry or deal with it at your desk.
- Stop it if it's heading the wrong way.
All of this needs that computer to be online, and depends on what the agent's connector supports and what state the task is in. For Codex, approvals can be answered from the phone for sessions started on the phone and for sessions in a desktop app opened through BotBus's "Launch Codex" (more in monitoring Codex from your iPhone). Sessions BotBus only reads still show status and send pushes, but you may not be able to answer for them from the phone. Some agents have no approval step at all (Pi doesn't), so you only get completed and failed. The notification itself has no "Allow" button; you approve on the task screen, which means you see the full request before deciding. For the Claude Code side, see approving Claude Code from your phone.
What happens to the notification text
The BotBus relay hands Apple's push service only a fixed phrase ("A task is waiting for your approval", "A task is done" and two others) plus an encrypted blob. A notification extension on the iPhone decrypts the blob with the key from pairing and swaps in the real title, body and computer name. Neither the relay nor Apple can read the content. On Android, the Firebase message likewise carries only routing fields and the encrypted blob, which is decrypted on the phone before anything is shown.
Two trade-offs. Apple Watch has no notification extension, so the watch always shows the fixed phrase and you tap in to see what's actually being asked. And the relay can see the push category (approval, question, completed, failed) and when it was sent, because it needs that to route. The full picture is in the security overview.
Limits
- A sleeping computer sends nothing. BotBus on the computer is what notices state changes. Asleep, lid closed or offline, it sees nothing. BotBus doesn't keep your computer awake; use system settings or something like
caffeinatefor long runs. - You have to allow notifications. The iPhone asks after you pair. If you declined, turn it back on in Settings.
- Android's first pushes may be late. Until the first real push arrives, Android checks every 15 minutes as a fallback. Phones without Google Play services don't get real-time pushes.
- Very short tasks right at startup can slip through. BotBus starts with a silent baseline, so a brand-new task that appears and finishes within one check interval may not trigger "completed".
- Claude Code's idle reminder. Claude Code emits
idle_promptafter a turn ends and the prompt sits idle. BotBus treats such a session as waiting for you, so you may get a "waiting for your answer" push after the "completed" one. - No per-category mute. You can't switch off one type of push inside BotBus today. Use the system's notification settings or a Focus mode.
- It only knows what the computer knows. If an agent hangs on a network call or rate limit without erroring or exiting, the task state doesn't change and nothing fires.
FAQ
I already have a Claude Code Notification hook. Will BotBus's hooks conflict with it?
No. The BotBus installer only adds and removes hooks carrying its own marker, so your Notification and Stop hooks keep running. With both active you'll get two pushes; turn off whichever you don't need.
Will I get a push when Codex is waiting for approval?
Yes. Codex's own notify doesn't cover approvals, but BotBus pushes as soon as a Codex task enters "waiting for approval". For phone-started sessions and desktop sessions opened through "Launch Codex", you can approve or deny right from the task. The computer has to be online with BotBus running. If you've turned on BotBus auto-approve for a project, approvals it lets through in phone-started turns don't send a push.
Can I approve from my Apple Watch?
Yes, inside the watch app: tap the push, open the task, read the request and approve or deny. The push itself only shows the fixed phrase. More in using an Apple Watch with coding agents.
Can the relay read my notifications?
Not the content. Title, body and computer name are encrypted on your devices; the relay forwards ciphertext and a fixed phrase. It does see metadata like the category and timing.
How do I get started?
Install BotBus on your computer, scan the pairing QR code with your phone and allow notifications. Downloads are on the home page: Mac (macOS 26 or later) and Linux for the computer, iPhone and Apple Watch on the App Store (iOS 26 / watchOS 26 or later), and an Android app (Android 8.0 or later) as a direct download.