Get a phone notification when OpenAI Codex finishes a task

Updated October 17, 2026

Codex can run an external program each time it finishes a turn. Point its notify setting at a ten-line script and you get a NextMsg push with Codex's summary. Or add the @nextmsg/mcp server so Codex can call notify_human itself.

First, install the NextMsg app, copy your send key from Settings and set it in your shell profile:

export NEXTMSG_KEY="nextmsg_live_YOUR_KEY"

Option 1: the notify setting

Codex passes a JSON description of the event as the program's only argument. Save this as ~/.codex/nextmsg_notify.py:

#!/usr/bin/env python3
# Codex notify hook: sends a push when Codex finishes a turn.
import json, os, sys, urllib.request

event = json.loads(sys.argv[1])
if event.get("type") != "agent-turn-complete":
    sys.exit(0)

summary = (event.get("last-assistant-message") or "Turn complete").strip()
request = urllib.request.Request(
    "https://api.nextmsg.app/v1/send",
    data=json.dumps({"message": f"Codex: {summary}"[:640], "channel": "codex"}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NEXTMSG_KEY']}",
        "Content-Type": "application/json",
    },
)
urllib.request.urlopen(request, timeout=10)

Then add one line to ~/.codex/config.toml, at the top level (with your real home path):

notify = ["python3", "/Users/you/.codex/nextmsg_notify.py"]

The message includes the start of Codex's last reply, which can contain code from your project. NextMsg deletes messages from the server after 72 hours; if you'd rather not send any of it, replace summary with a fixed text such as "Codex finished".

Option 2: the MCP server

The @nextmsg/mcp server gives the agent a notify_human tool. It is open source: source on GitHub, package on npm.

codex mcp add nextmsg --env NEXTMSG_KEY=nextmsg_live_YOUR_KEY -- npx -y @nextmsg/mcp

Or add it to ~/.codex/config.toml by hand. env_vars forwards the key from your environment, so it isn't written into the file:

[mcp_servers.nextmsg]
command = "npx"
args = ["-y", "@nextmsg/mcp"]
env_vars = ["NEXTMSG_KEY"]

Codex can now call notify_human(message, channel?). Add a line to your AGENTS.md so it does:

When you finish a task that took more than a few minutes, or you are blocked
and need my input, call notify_human with a one-line summary.

Which one to use

  • notify: fires after every turn. Great for long autonomous runs; chatty in quick back-and-forth sessions.
  • MCP server: Codex decides, so you hear about outcomes rather than every turn.

More guides