guide / hooks

Claude Code hooks: get a phone notification when it needs you

This is the free way to know when Claude Code is waiting for you. A hook runs a command when the agent asks for permission or stops, and that command pushes a message to your phone through ntfy.

1. Pick a private topic

Install the ntfy app on your phone and subscribe to a long random topic name, for example agent-7f3k9q2x. Anyone who knows the topic can read it, so make it unguessable, or self-host ntfy.

2. Add the hooks

In ~/.claude/settings.json (or a project's .claude/settings.json), add commands for the Notification event, which fires when Claude needs permission or has been idle waiting, and for Stop, which fires when it finishes a turn:

{
  "hooks": {
    "Notification": [
      { "hooks": [ { "type": "command",
        "command": "curl -s -d 'Claude Code needs you' ntfy.sh/agent-7f3k9q2x" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command",
        "command": "curl -s -d 'Claude Code finished' ntfy.sh/agent-7f3k9q2x" } ] }
    ]
  }
}

Check the current hooks reference in Claude Code's documentation for the exact schema in your version, since it has changed over time. Run /hooks in Claude Code to confirm they are registered.

3. Keep the noise down

A push on every stop gets ignored fast. Keep only the events you act on, and tell the agent in CLAUDE.md to ask you only about irreversible or design-changing decisions.

Where a push is not enough

A banner is easy to miss, especially overnight, and it can't carry your answer back: you still have to open a terminal. If you want to answer by voice and have the agent continue, that is what a phone call is for. I built JustCallMe for that case: one HTTPS call from the agent, your phone rings, you answer in a sentence. Unanswered calls are free and new accounts get 20 free minutes. For a free option, the hooks above are a good answer; see the full comparison of every approach.