Notifications for AI coding agents: Claude Code and Codex side by side

For every method on one agent, sound and phone included, read the Claude Code notifications guide or the Codex notifications guide. This is the side-by-side, as the Claude Code hooks reference and terminal guide, the Codex hooks page and advanced configuration stood on the date above.

Both hook files nest the same way: an event, a matcher group, then a list of handlers. Both also run a handler in the session's working directory. So one script can do the work, and each agent's file only passes in its name and what happened.

#!/bin/sh
# One alert for Claude Code and Codex. Usage: agent-notify AGENT WHAT
agent="${1}"
what="${2}"
text="$what in $(basename "$PWD")"
case "$(uname -s)" in
  Darwin) osascript -e 'on run argv' \
    -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
    -e 'end run' "$text" "$agent" ;;
  *) notify-send "$agent" "$text" ;;
esac >/dev/null 2>&1
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/agent-notify 'Claude Code' 'Finished'",
            "async": true
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/agent-notify 'Claude Code' 'Needs approval'",
            "async": true
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/agent-notify 'Claude Code' 'Waiting for you'",
            "async": true
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/agent-notify 'Codex' 'Finished'",
            "async": true
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.local/bin/agent-notify 'Codex' 'Needs approval'",
            "async": true
          }
        ]
      }
    ]
  }
}

1. Make it runnable

   Run mkdir -p ~/.local/bin before you save the file, and chmod +x ~/.local/bin/agent-notify after.

2. Try it by hand

   Run ~/.local/bin/agent-notify 'Codex' 'Finished' in a project folder. No alert here means the script is at fault, not the hooks.

3. Trust it in Codex

   Type /hooks inside Codex and trust the two new entries.

4. Accept the folder in Claude Code

   It holds back every settings-file hook, your own included, until you accept the workspace trust dialog for that folder.

With one agent, an alert means that agent. With two, the alert also has to say which one, and the number of alerts doubles.