How to get notified when Claude Code or Codex needs input

A coding agent that stops for a permission prompt does nothing until you notice. Most of the time lost with agents isn't the agent being slow; it is the agent sitting at “Allow this command?” in a tab you aren't looking at. Here is how to get a notification when Claude Code or Codex needs you, or has finished.

Claude Code: hooks

Claude Code runs commands on events you choose, configured as hooks in a settings file: ~/.claude/settings.json for every project, or .claude/settings.json in one repository. Two events matter here:

• Notification fires when Claude Code sends a notification. Its matcher picks the type: permission_prompt for permission requests, idle_prompt when it is waiting for your input. Leave the matcher out to catch every notification.
• Stop fires when Claude finishes responding.

On Linux, with notify-send:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Needs permission'" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Finished'" }
        ]
      }
    ]
  }
}

On macOS, swap the command for osascript -e 'display notification "Finished" with title "Claude Code"'. A hook receives details about the event as JSON on standard input, so a small script can include the project name in the message. The hooks reference lists every event and matcher.

Codex: notify and TUI notifications

Codex has two settings in ~/.codex/config.toml. The simple one asks the terminal itself to notify you:

[tui]
notifications = true                 # or a list of event types
notification_condition = "unfocused" # or "always"
notification_method = "auto"         # auto, osc9 or bel

That uses an OSC 9 desktop notification or the terminal bell, depending on what your terminal supports. For a custom action, notify names a program that Codex runs with a JSON description of the event:

notify = ["python3", "/home/me/bin/codex-notify.py"]

Check the Codex configuration reference for the event types your version sends.

Where per-agent hooks fall short

Hooks work, but they get awkward once you run several agents:

• Each agent needs its own setup, in its own format, on every machine.
• A notification tells you something needs you, not which of five sessions, and getting there means hunting through tabs.
• Agents without hooks give you nothing.

One setup for every agent with Hive

Hive watches every agent's screen itself, using per-agent rules for Claude Code, Codex, Gemini CLI, OpenCode and about twenty more, so it needs no setup inside the agents. Its sidebar shows each agent as working, needs input or done, across every project, and the terminal bell rings when an agent you aren't viewing needs you or finishes. For desktop notifications, add two lines:

# ~/.config/hive/config.toml
[integrations.desktop_notify]
enabled = true

By default that runs notify-send; set command to anything else (Hive passes the title and body as its last two arguments). When the notification arrives, Alt+1–9 jumps straight to the agent, whichever project it is in. Scripts and agents without rules can report their state with hive report-agent.

You can use both: keep a Stop hook that runs your tests, and let Hive handle the “come back, I need you” part for every agent at once. See live agent status and desktop notifications.