How to Get Notified When Your Coding Agent Finishes or Needs You

Published August 20, 2026 · by the AQ team

Both Claude Code and Codex CLI can tell you when they are done or blocked, and neither does it well by default. In Claude Code, the fastest fix is one line in your settings: set preferredNotifChannel to terminal_bell for a beep, or add a Notification hook to run any command you like (a desktop popup, a sound, a phone push). In Codex CLI, the equivalents are the notify key in config.toml, which runs an external program when a turn completes, and the tui notifications setting for desktop alerts. This guide covers both, the tmux and SSH complications that break notifications on a remote box, and the point past which no notifier helps, all verified against vendor documentation as of August 2026.

First, separate the two events you care about

"Is it done?" is really two different questions, and they want different alerts:

• Blocked and waiting on you. The agent hit a permission prompt or asked a clarifying question. Nothing is happening until you answer. Every second here is wasted wall-clock time.
• Finished the turn. The agent produced its result. Nothing is wasted while you finish what you were doing, but a diff is now waiting for review.

Blocked deserves an interrupting alert; finished usually does not. Wire both to the same loud channel and you will mute the channel, which puts you back where you started. Decide which one you actually want pushed before configuring anything.

Claude Code: the built-in signals

Claude Code fires a notification event when it finishes a task or pauses for a permission prompt and you appear to be away from the terminal. What happens next depends entirely on your terminal emulator. As of August 2026, Anthropic's terminal configuration documentation states that Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In every other terminal, including Warp and the VS Code integrated terminal, nothing visible happens until you configure it.

The one-line fix for those terminals is the terminal bell, set in your user settings file:

// ~/.claude/settings.json
{
  "preferredNotifChannel": "terminal_bell"
}

One detail matters for remote work: the desktop notification travels over SSH to your local machine, so an agent on a server can still alert you at your desk. Ghostty and Kitty forward it to the OS notification center with no setup, while iTerm2 needs it enabled under Settings, Profiles, Terminal: check "Notification Center Alerts", then click "Filter Alerts" and enable "Send escape sequence-generated alerts".

Claude Code: hooks, for anything the bell cannot do

Hooks are shell commands Claude Code runs at defined points in its lifecycle: any command, any channel. The Notification event fires when Claude is waiting for input or permission, and Anthropic's own first-hook walkthrough is exactly this case:

// ~/.claude/settings.json  (macOS)
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

On Linux the command is notify-send 'Claude Code' 'Claude Code needs your attention'. Run /hooks in the CLI to confirm the hook registered. Three things are worth knowing before you build on this:

• The matcher filters by notification type. Documented values as of August 2026 include permission_prompt, idle_prompt, agent_needs_input, and agent_completed, so you can route "blocked" and "finished" to different channels instead of one undifferentiated ping.
• Hooks add to the built-in notification rather than replacing it. Terminals that get no desktop notification can use a hook or the terminal bell; you are not choosing one mechanism over another.
• Stop is the other useful event. Stop fires when Claude finishes responding, once per turn, and receives the final assistant message, which makes it the right hook for "summarize what just landed" alerts. When a turn ends on an API error, StopFailure fires instead, so an alert wired only to Stop will silently miss failed turns.

Notification hook output and exit code are ignored, so a broken command fails quietly. Test it by hand before trusting it.

Codex CLI: notify and TUI notifications

Codex CLI has two separate mechanisms, and the difference between them catches people out. The top-level notify key in ~/.codex/config.toml holds an argv array; Codex runs that program and hands it a JSON payload when an agent turn completes. Separately, the tui notifications setting drives desktop alerts from the terminal UI and accepts either a boolean or a filtered list of event types, including agent-turn-complete and approval-requested.

# ~/.codex/config.toml
# Root keys must appear before any table headers in TOML.
notify = ["/Users/you/bin/agent-alert"]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

The gap: as of August 2026, the external notify hook still only receives agent-turn-complete. Approval requests reach the TUI desktop notification but not your external script, which is the exact ask in open issue 19921 in the openai/codex repository (filed April 28, 2026, and still open at the time of writing). So in Codex, script your own alerting for "finished" and lean on the built-in TUI notification for "needs approval".

Getting the alert onto your phone

Desktop notifications assume you are at the desk. For longer runs, publish to a push service instead. ntfy is the common choice: an open-source HTTP pub-sub service (dual licensed Apache 2.0 and GPLv2) where you publish to a topic with one HTTP POST and no account, subscribe on the open-source Android or iOS app, and self-host the server if you would rather not use the public instance. Because the hook is just a shell command, the wiring is one curl:

curl -d "Claude Code needs your attention" ntfy.sh/your-private-topic-name

Topics on the public server are unauthenticated by default, so treat the topic name as a secret, keep code details out of the message, and self-host if that is not good enough for your organization.

The remote-VM catch

If your agents run on a server, which is where longer sessions belong, two things break. First, notify-send needs a desktop notification daemon; headless servers, SSH sessions, and most containers do not have one, so the Linux example above fails silently on exactly the machine you most want alerts from. A push service sidesteps this, since curl needs no desktop. Second, tmux swallows the escape sequence that carries desktop notifications to your outer terminal, so it needs passthrough enabled:

# ~/.tmux.conf
set -g allow-passthrough on

Then run tmux source-file ~/.tmux.conf to apply it to the running server. tmux can also do a coarse version of this itself, with no agent support required, by flagging windows that produce output or ring the bell:

# ~/.tmux.conf
setw -g monitor-bell on
setw -g monitor-activity on
set -g visual-activity on

That marks any window that moved in the status line: a reasonable safety net for a handful of panes, and useless noise past that.

Where notifications stop being the answer

Notifications solve one problem well: you are one person, at one machine, running one or two sessions, and you want your attention back. They degrade on two axes. Add sessions and every alert becomes ambiguous (which one was that?) until you are context-switching on a schedule set by whichever agent finishes first. Add teammates and the alert reaches whoever started the session, not whoever has attention free right now.

That second failure has been measured. A July 2026 LeadDev analysis of 25,264 agent-generated pull requests across 2,361 popular GitHub repositories found that in 79 percent of agentic pull requests the same developer both reviewed and modified the agent's contribution, and only about one in eight workflows involved multiple humans. When a session is visible only to the person whose laptop it runs on, a notifier can ping only that one person, and the review collapses into self-review. Our guide on how many coding agents one developer can run works through the attention ceiling this creates.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. To be direct: AQ is not a notification service, and nothing here replaces the hooks above. Keep them. What changes is where the session lives, which is the part a notifier cannot fix.

Agents run as real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or plain shells) in persistent tmux sessions on your team's VM, streamed live to the browser. Sessions survive a closed laptop and resume from any device, and AQ is browser-based on macOS, Windows, Linux, and mobile, so "check whether it is done" means opening a workspace from your phone rather than needing an alert to find you. Teammates open the same workspace and watch the same live session, so "who picks this up" stops being "whoever got the notification": typing into someone else's terminal is delegated by its owner approving a control request in one click, and the owner keeps their own input. Visibility stays owner-managed, either team-visible or private and shared with specific people. Each engineer signs into the CLIs with their own Claude or OpenAI account, and each workspace gets its own isolated git worktree.

Pricing is two plans. Free is a personal sandbox for one person: AQ creates a private machine in an isolated network, nothing to install, no time limit. Team is $50 per user per month in early access (standard $200, billed monthly), covering VMs you connect from your own cloud or a dedicated always-on AQ-managed VM in its own isolated network, with your rate locked for your first 12 months.

Plainly: if you run one or two sessions on your own machine, a Notification hook and a phone push are the whole answer, and this guide is enough. AQ earns its place when sessions must outlive laptops and more than one person needs to see them.