Claude Code notifications: know the moment it finishes — or needs you
The most expensive part of running Claude Code isn't the tokens — it's the checking. The agent works for ten minutes, you alt-tab every ninety seconds "just in case", and half the time it's been sitting on Allow bash command? (y/n) since you looked away.
The fix is to invert the flow: instead of you polling the terminal, the terminal notifies you — and only at the three moments that matter.
The three notifications that matter
- Waiting for input — Claude hit a permission prompt (y/n or a numbered choice) and is blocked on you. This is the urgent one.
- Task completed — the run finished; review whenever you like.
- Error — the process crashed or exited unexpectedly.
Same machine? A hook is enough
If you just want a desktop popup while you're at the computer, Claude Code's own hooks can run a local notifier on Stop and Notification events — no extra services involved.
Away from the machine? That's what TermIQ is for
A desktop popup dies at the edge of your desk. TermIQ relays the terminal itself, so the notification reaches your phone as a real push — and tapping it opens the live terminal with the prompt parsed into buttons. Answer the y/n with one tap from the couch, the street, or another country:
npx @termiq/cli
Free tier: 1 agent, 2 terminals, no card. Notification types are configurable per event (waiting / completed / errors) in settings.
FAQ
- Can Claude Code send notifications natively?
- Claude Code has hooks (Stop, Notification) that can run a local command — good for a desktop popup on the same machine. For notifications that reach your phone when you are away, you need a relay like TermIQ.
- Which events trigger a notification?
- Three: the task finished, the agent is waiting for your input (a y/n or numbered permission prompt), and an error or crash. Each type can be toggled separately in settings.
- Can I answer the prompt from the notification?
- Yes — tapping the notification opens the live terminal in the PWA, with the detected prompt parsed into buttons. Answering a y/n is one tap.
- Is the notification content private?
- By default the push carries status metadata only ("a terminal needs input") — not the question itself, so the server never sees it. The agent has a setting that puts the question text in the notification instead; it is off until you turn it on, since that text then passes through the server. The terminal stream itself is end-to-end encrypted between your devices either way.