A WhatsApp message when Codex finishes

You handed Codex a long task and left the desk. Two ways to hear from it on the app already open on your phone — a message when it is done, and a question with buttons before it does something you would want a say in.

The two routes do different jobs. The notify hook is Codex telling you a turn finished; it is built into the CLI and fires whether or not the agent thinks to say anything. The MCP server lets the agent itself message you in its own words, and — the part the hook cannot do — ask you something and wait for the answer before acting.

Both send over Meta's official Cloud API, and neither needs a WhatsApp number of your own, a Meta business account or an approved message template, because the number and the template are ours. You need an API key, which starts jak_ and is made under Management then Approvals in the dashboard. The first three messages are free.

Route one: the notify hook

Codex's CLI has one external notification hook: the root-level notify key in ~/.codex/config.toml. When a turn completes, Codex runs the program you name and passes a single argument — a JSON object whose type is agent-turn-complete and which includes last-assistant-message.

Put this in ~/.codex/notify-whatsapp.sh and make it executable:

#!/usr/bin/env bash
# Codex notify hook -> a WhatsApp message. Codex passes the event as $1.
set -uo pipefail

payload="${1:-}"

said=$(printf '%s' "$payload" \
         | jq -r '."last-assistant-message" // empty' 2>/dev/null | head -c 600)

# jq builds the body so a quote or a newline in what Codex said cannot
# break the JSON. The message routinely contains both.
curl -sS --max-time 10 https://api.jabee.ai/api/v1/alerts \
  -H "Authorization: Bearer $JABEE_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "Codex finished a turn" \
              --arg b "${said:-Finished with nothing to report.}" \
              '{title: $t, body: $b}')" >/dev/null

# Always succeed: a notifier that fails the hook is worse than no notifier.
exit 0

Then point Codex at it. notify is a root-level key, and in TOML root-level keys must come before any [section], so put it at the top of ~/.codex/config.toml:

notify = ["bash", "/Users/you/.codex/notify-whatsapp.sh"]

Two things worth knowing before you paste it:

Route two: the MCP server, so the agent can ask

A hook can only tell you things. With the MCP server, Codex can tell you what it actually did, and ask before doing something irreversible. One command adds it:

codex mcp add jabee --env JABEE_API_KEY=jak_... -- npx -y @jabee/mcp

Or the equivalent in ~/.codex/config.toml:

[mcp_servers.jabee]
command = "npx"
args = ["-y", "@jabee/mcp"]
env = { JABEE_API_KEY = "jak_..." }

That gives three tools. tell_person sends a WhatsApp message — the agent's own "done", in its words, which beats the hook's because it knows what it did. ask_person sends a question with approve, skip and edit buttons and blocks until somebody taps one, or for wait_seconds, after which it hands back a request id. check_approval reads that id later.

The sentence that makes it work goes in your AGENTS.md, because an agent will not ask unless it is told to:

Before anything irreversible — a force push, a production deploy, a
migration, deleting a branch, spending money — call ask_person and wait
for the answer. When a long task finishes, call tell_person with one
line on what changed.

Now the run that used to end in a question you were not there to answer ends in a WhatsApp message with three buttons on it. The MCP reference lists every argument.

Which one to use

You wantUse
To know the turn ended, always, even if the agent said nothing usefulthe notify hook
A summary of what it did, in its wordstell_person
To approve or refuse something before it happensask_person
A sound while you are at the deskCodex's own [tui] notifications
The same thing from Claude Codethe Claude Code page, which has a third route
None of the above, from a CI run rather than your laptopthe alerts endpoint directly

What it costs

$29 a month for 500 alerts and approvals together, then 3 cents each. The first three are free, so you can wire the hook up and watch one land before paying for anything. There is no per-seat charge and no charge for the MCP server.

Questions

Does the notify hook fire when Codex needs my approval?

No. The hook currently fires only for agent-turn-complete. Approval prompts surface in the terminal UI, which can ring a bell or show a desktop notification, but no external program runs. If the thing you want is to be asked on your phone, use ask_person over MCP — the agent asks before acting and waits for the answer.

Do I need a WhatsApp number or a Meta developer account?

No. Neither, at any point. The message goes out on our registered, Meta-verified number using our approved template, so you need an API key and nothing else. There is no number of yours involved, so there is nothing of yours to get banned.

Who can it message?

Your own people, once they have verified their phone — which they do by tapping a link in the dashboard and sending one message. It will not message your customers, and that is deliberate: a shared number messaging strangers is what gets numbers banned.

Does this work for Codex running in the cloud, or only the CLI?

The notify hook and codex mcp add are features of the CLI on your own machine. A cloud task that can reach the internet can still send the same message with one curl to the alerts endpoint; there is nothing agent-specific about it.

Why WhatsApp rather than a push notification app?

Use a push app if you like having one. The case for WhatsApp is that it is already on your phone, already exempted from your notification triage, and the reply box is the same place the question arrives — approve, skip or type what to do instead, without installing or opening anything new.