---
title: "Get a phone alert when Claude Code or Codex finishes"
description: "A private phone alert when Claude Code or Codex finishes: a hook posts to your own ntfy server, reached only over Tailscale."
canonical_url: https://antonio-amore-akiki.vercel.app/guides/claude-code-phone-alerts/
last_updated: 2026-11-17
---

# Get a phone alert when Claude Code or Codex finishes

A private phone alert when Claude Code or Codex finishes: a hook posts to your own ntfy server, reached only over Tailscale.

You start a long task in Claude Code or Codex, walk away, and want your phone to buzz when it is done. This guide sends that [push notification](https://en.wikipedia.org/wiki/Push_technology) to your own [ntfy](https://docs.ntfy.sh/) server on your own computer, reached over [Tailscale](https://en.wikipedia.org/wiki/Tailscale), so the text of your work never passes through a public notification service.

## What you need

| Part | What it does | Source |
|---|---|---|
| [Tailbell](https://antonio-amore-akiki.vercel.app/tailbell/) | runs ntfy as a Windows service on `127.0.0.1:8091` and shares it with your phone through Tailscale Serve | [Tailbell README](https://gitlab.com/antonio-amore-akiki/tailbell) |
| Tailscale on the computer and the phone | puts both on your private network (tailnet) | [Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) |
| The ntfy app on the phone | shows each message as a notification | [ntfy documentation](https://docs.ntfy.sh/) |
Table: The three parts of a private phone alert for AI agents and where each is documented

Tailscale Serve "lets you share a local service securely within your Tailscale network", and Tailbell keeps it that way by default: public Funnel needs an explicit flag. The phone uses the address `https://your-device.your-tailnet.ts.net` with no port number.

## Step 1: set up the server

Run `WhispergateSetup.exe` from the [latest Tailbell release](https://gitlab.com/antonio-amore-akiki/tailbell) (the setup file keeps the project's former name). The wizard checks Windows, Tailscale and MagicDNS, installs the ntfy service and prints the server address, the user name and the topics. Add that address in the ntfy phone app and subscribe to a topic, for example `agents`.

ntfy accepts a password or an access token for publishing. The [ntfy page on access tokens](https://docs.ntfy.sh/publish/#access-tokens) recommends a token when several programs publish, so you never copy your password into them. The examples below use one, written as `tk_yourtoken`.

## Step 2: Claude Code

Claude Code runs a `Stop` hook "when the main Claude Code agent has finished responding" ([Claude Code hooks](https://code.claude.com/docs/en/hooks)). Add this to `~/.claude/settings.json`, the settings file that applies to all your projects:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -H \"Authorization: Bearer tk_yourtoken\" -d \"Claude Code finished\" https://your-device.your-tailnet.ts.net/agents"
          }
        ]
      }
    ]
  }
}
```

The `Stop` hook does not run when you interrupt Claude Code yourself, so the alert means the agent really finished.

## Step 3: Codex

Codex runs the program named in `notify` "whenever Codex emits supported events (currently only `agent-turn-complete`)" and passes it one JSON argument, which includes `last-assistant-message` ([Codex advanced configuration](https://developers.openai.com/codex/config-advanced)). Codex adds that argument at the end, so it needs a small script rather than a bare `curl`. Save this as `notify_phone.py`:

```python
import json
import sys
import urllib.request

event = json.loads(sys.argv[1])
if event.get("type") == "agent-turn-complete":
    text = (event.get("last-assistant-message") or "Codex finished")[:300]
    request = urllib.request.Request(
        "https://your-device.your-tailnet.ts.net/agents",
        data=text.encode(),
        headers={"Authorization": "Bearer tk_yourtoken"},
    )
    urllib.request.urlopen(request)
```

Then point Codex at it in `~/.codex/config.toml`:

```toml
notify = ["python3", "/path/to/notify_phone.py"]
```

Your phone now shows the first lines of Codex's last answer when a turn ends.

## Test the whole path

Tailbell's `scripts\verify.ps1` checks health, publishing, receiving and the websocket, and `scripts\doctor.ps1` prints a full report with fix hints. A test message from the computer proves the path to the phone:

```text
curl -H "Authorization: Bearer tk_yourtoken" -d "test" https://your-device.your-tailnet.ts.net/agents
```

[Read more about Tailbell](https://antonio-amore-akiki.vercel.app/tailbell/), free and open source under the MIT license.

Written by [Antonio Amore Akiki](/), aerospace and manufacturing engineer in Enschede, the Netherlands.

## Frequently asked questions

### How do I get a phone notification when Claude Code finishes?

Add a Stop hook to ~/.claude/settings.json that sends a message to an ntfy topic. Claude Code runs the Stop hook when the main agent has finished responding. The ntfy app on your phone shows the message.

### How do I get a phone notification when Codex finishes?

Set notify in ~/.codex/config.toml to a small script. Codex runs it with one JSON argument on every agent-turn-complete event, and the script sends the last message to your ntfy topic.

### Do the alerts go through a public server?

No. With Tailbell the ntfy server runs on your own computer, and Tailscale Serve shares it only inside your own tailnet. Public Funnel stays off unless you turn it on yourself.

### What does it cost?

Nothing. Tailbell is free and open source under the MIT license, and ntfy and the ntfy phone app are free.


By Antonio Amore Akiki, aerospace and manufacturing engineer: https://antonio-amore-akiki.vercel.app/about/
Canonical page: https://antonio-amore-akiki.vercel.app/guides/claude-code-phone-alerts/
