Make Claude Code Text You When a Task Finishes

We run Claude Code on long jobs often enough that checking the terminal became its own task. A migration script chewing through a large table, a refactor Claude is still working through, a permission prompt sitting untouched because we stepped away from the desk: all three look identical from across the room, which is to say invisible. Beam is an independent messaging platform, not a feature built by Anthropic or Apple, so none of what follows is a hidden setting buried inside Claude Code itself. It is a few lines in a config file most developers already have open, pointed at a service that happens to own a phone line.

A thread on Anthropic's own plugins repository asks for exactly this capability: some way to know Claude finished without refreshing a terminal window every few minutes (GitHub issue #798). This is not a one-off complaint. Developers already run personal notification bots that ping a phone through Telegram or a push service just to avoid that exact kind of babysitting, which says the terminal's silence is the real defect here, not any particular task Claude happens to be running.

Three situations deserve a different reaction, and Claude Code already tells them apart if you listen for the right signal. A long job that finishes clean is good news you can act on whenever you get back to your desk. That same job hitting an API error partway through is bad news you want sooner rather than later. A permission prompt sitting there waiting for a yes or no is neither; it is a stalled clock, and the longer it sits unanswered, the more of the session you lose for nothing. Treating all three as one generic "Claude did something" alert is why most people give up on notifications after the first noisy afternoon.

Plenty of developers already use a one-line curl inside the hook command for this, aimed at a push service. One widely shared setup pipes the Stop hook into ntfy, a free alert relay, gated behind a sentinel file so it only fires during unattended runs (noahcoffey.com). A second guide extends the same idea across both the Stop and Notification hooks, and flags that the Notification hook's exit code is ignored entirely, so you have to test the command by hand rather than trust a clean hook registration (aq.dev). Both work. Neither one puts the alert where a text message already lands.

Beam's REST API takes the same curl pattern and points it at a phone number instead of a push topic. Create a workspace credential once, under Settings, then API key, and send it as an x-api-key header on a request to https://beam.aisync.link/v1/messages. That request body needs only a recipient and a message; Beam picks iMessage when the recipient's phone supports it and falls back to SMS otherwise, queues the send, and hands back an id you can check on later.

1. In Beam, open Settings, then API key, and copy the workspace key. It will not be shown to you again, so paste it somewhere private before doing anything else.
2. Save a short script, for example ~/.claude/notify-beam.sh, that reads a message from its first argument and curls it to Beam.
3. Make the script executable, then run it once by hand from a terminal, sending yourself a real text, before wiring it into Claude Code at all.
4. Open .claude/settings.json in the project, or ~/.claude/settings.json for every project, and add a Stop entry pointing at the script with a "done" style argument.
5. Add a StopFailure entry with a different argument, so a failed run reads differently from a clean one when the text arrives.
6. Add a Notification entry matched to permission_prompt and agent_needs_input only, so you are not texted for every routine notification Claude Code sends.
7. Restart Claude Code, or open a fresh session, so it rereads the edited settings file.
8. Run one real task, long enough to finish on its own, and confirm the text arrives before trusting the setup with anything unattended overnight.

That script stays short:

MESSAGE="${1:-Claude Code needs you}"
curl -s -X POST https://beam.aisync.link/v1/messages \
  -H "x-api-key: $BEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"to\": \"$MY_PHONE\", \"message\": \"$MESSAGE\"}"

Keep BEAM_API_KEY and MY_PHONE as environment variables set in your shell profile, never pasted directly into the script. That is the same reasoning Beam's own developer docs give for connection tokens generally: a credential sitting in plain text in a file you might commit by accident is a credential you will eventually have to revoke.

Before you let any Beam-wired hook run unattended:
- The script tested by hand from a terminal, with a real text landing on your phone
- Stop and StopFailure read differently, not the same message for a clean run and a crashed one
- Notification matched only to permission_prompt and agent_needs_input, not every notification Claude Code sends
- BEAM_API_KEY and your phone number stored as environment variables, never pasted into the script itself
- One full overnight run checked the next morning against what Beam's inbox actually shows

Skipping the last line is the most common shortcut, and the most expensive one. A hook that fires correctly on a short test task can still go quiet on a long one if the environment variables it needs are not present in whatever shell actually launches Claude Code overnight, as opposed to the interactive shell you tested it in by hand.

Not for this. Beam's iMessage and RCS channels do not require the carrier A2P 10DLC registration process that SMS numbers go through, and texting your own phone from your own workspace is about as low-risk a use case as sending gets. That changes the moment you point the same hook at a teammate instead of yourself: SMS fallback, used when someone's device or carrier does not support RCS, stays subject to the applicable carrier A2P rules, and consent and opt-out handling still apply to anyone besides you.

This is a different integration from connecting Claude Code to iMessage over MCP, which lets the agent itself read a conversation and draft a reply while you are in the session approving each step. The hook pattern covered here runs after you have already walked away, when there is no one watching the session to approve anything. For the fuller permission model, the tool catalog, and the difference between a scoped MCP connection token and a plain workspace API key, our MCP server guide goes deeper on that distinction. And if you already rely on Claude Desktop's local bridge for a separate workflow, this hook setup does not touch that configuration at all, since it talks to Beam's REST API directly instead of going through MCP.