Claude Code notifications on your iPhone

What Claude Code does by itself

When Claude Code finishes a task or stops at a permission prompt and you appear to be away from the terminal, it raises a notification event. What you see depends on the terminal. According to the Claude Code terminal documentation, a desktop notification is sent by default only in Ghostty, Kitty, and iTerm2. In other terminals, including Apple's Terminal, you get nothing until you turn on the terminal bell or add a hook.

• Ghostty and Kitty pass the notification to macOS Notification Center without further setup.
• iTerm2 needs forwarding switched on: in Settings, Profiles, Terminal, check Notification Center Alerts, then open Filter Alerts and enable Send escape sequence-generated alerts.
• Inside tmux, notifications are swallowed unless allow-passthrough is on.

All of that stays on the Mac. To hear about it on your phone, pick one of the three routes below.

Route 1: Claude Code's own mobile push

Claude Code can push to the Claude mobile app while a session is connected through Remote Control. This is the route with the least to set up, and it needs nothing extra on the Mac.

1. Install the Claude app on your iPhone and sign in with the same account you use for Claude Code.
2. Allow notifications when iOS asks.
3. Start the session with Remote Control active.
4. In the terminal, run /config and enable Push when Claude decides, Push when actions required, or both.

Things to know, from the Remote Control documentation: Remote Control is available on Pro, Max, Team, and Enterprise plans and does not work with API keys or third-party model providers. Claude decides when a push is worth sending, and beyond those two switches there is no per-event configuration. Pushes are skipped while you are typing in or focused on the connected terminal. The session runs on your machine, so the computer has to stay on.

Route 2: a hook that publishes to ntfy

Claude Code hooks run a command of your choice at fixed points in a session. A Notification hook fires when Claude is waiting for input or permission, which makes it a good place to publish a message to the free ntfy service. Install the ntfy app on your iPhone, subscribe to a long, hard-to-guess topic name, and add this to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -d 'Claude Code needs your attention' https://ntfy.sh/your-private-topic"
          }
        ]
      }
    ]
  }
}

The empty matcher fires on every notification type. Set it to permission_prompt to hear only about approvals, or to idle_prompt for the case where Claude finished and you have not typed since. Run /hooks inside Claude Code to confirm the hook is registered.

This route is free and works in any terminal, on any plan. The cost is that it covers Claude Code only, and you maintain the configuration yourself.

Route 3: forward the Mac notification

The third route treats Claude Code like any other Mac app: let it post a normal macOS notification, and forward that notification to your iPhone with NotiFerry. Nothing in Claude Code needs to know about your phone.

First make sure the notification really reaches Notification Center. In Ghostty and Kitty it already does, and in iTerm2 it does once alert forwarding is on. In any other terminal, use the documented macOS hook instead:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

macOS routes this through Script Editor and shows nothing until Script Editor is allowed to notify. Run osascript -e 'display notification "test"' once, then turn on Allow Notifications for Script Editor in System Settings, under Notifications.

Then set up NotiFerry: authorize the Notification Center folder, subscribe your iPhone in the ntfy app, and confirm the phone test. From then on the Claude Code alert arrives on your phone along with those of any other Mac app you have not switched off. Title only is the default privacy mode, so the message text stays on the Mac unless you choose otherwise.

NotiFerry sees only the notification. It does not read your prompts, Claude's responses, your repository, or the terminal.

Which route fits

If Remote Control already fits how you work, use the built-in push. If you only care about Claude Code and are comfortable editing a settings file, the ntfy hook is hard to beat. NotiFerry earns its place when the same phone should also hear about builds, exports, and other tools, or when you would rather not maintain a hook per tool. See getting notified when a Mac task finishes for those cases.

All three have the same hard limit: the session runs on your Mac, so the Mac has to stay awake.