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:
- It fires on every completed turn, and only on completed turns.
agent-turn-completeis currently the only event the hook receives. A short back-and-forth session will message you a lot; this hook earns its keep on the long runs you walk away from. - It does not fire when Codex is waiting for your approval. The
terminal UI can notify on
approval-requested(the[tui]notificationssetting), but that is a terminal-side notification, not a program call — useful at the desk, silent from the sofa. Being asked on your phone is the MCP route below.
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 want | Use |
|---|---|
| To know the turn ended, always, even if the agent said nothing useful | the notify hook |
| A summary of what it did, in its words | tell_person |
| To approve or refuse something before it happens | ask_person |
| A sound while you are at the desk | Codex's own [tui] notifications |
| The same thing from Claude Code | the Claude Code page, which has a third route |
| None of the above, from a CI run rather than your laptop | the 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.