Quick answer
Claude Code signals two moments worth catching: when it finishes (the Stop event) and when it pauses to ask you something (the Notification event). Out of the box you only get a quiet terminal prompt. To actually be told, hook those events to something that reaches you — a terminal bell or desktop banner if you're at the machine, or a push notification or Live Activity on your phone if you've walked away. Hooking Stop alone covers 'it's done'; add Notification to also catch mid-task permission prompts.
Here's the frustrating part: Claude Code doesn't announce that it's done. It just... stops, returns you to the prompt, and waits. If you tabbed away to do something else, the agent might have finished — or stalled on a permission prompt — ten minutes ago while you had no idea. This guide covers every way to actually know, from the zero-effort terminal bell to a status card on your phone.
First, know what "done" means to Claude Code
There isn't one moment worth catching — there are two, and they're different events:
- Stop — the agent finished its turn and handed control back to you. This is "the task is done."
- Notification — Claude paused mid-task to ask you something, usually a permission prompt like
Allow: npm test?. This is "it needs you before it can continue."
If you only wire up one, wire up both concepts. Hooking Stop alone tells you when everything ends but leaves you blind to the stalls in between — which, for a long task full of permission prompts, is often where all the waiting actually happens.
"It's done" and "it needs me" feel like the same problem — tell me when to look — but they fire at different times. Cover both events or you'll catch the finish and miss every pause along the way.
The options, from least to most effort
1. The terminal bell (zero setup, only works at your desk)
Depending on your terminal, Claude Code can emit a bell character when it finishes, and your terminal app can turn that into a sound or a badge on the tab. It's free and instant — but it only helps if you're sitting at that machine with the terminal somewhere in view. Walk to the kitchen and it's useless.
2. A desktop banner (still tied to that Mac)
One step up: hook the Stop event to a command that shows a native desktop notification, so you get a banner even when the terminal is buried behind other windows. Better than the bell, but it still can't reach you once you've left the computer. The full setup — including turning your iPhone's Live Activity into a Mac menu-bar indicator — is in the desktop notifications guide.
3. A push notification to your phone (works anywhere)
This is the one that actually solves "I walked away." Point the Stop and Notification hooks at a webhook that sends a push to your phone, and you'll get an alert the moment the agent finishes or stalls — from the next room or the next building. Setup is a one-time hook; see how to get Claude Code notifications on your iPhone.
4. A Live Activity (glanceable, no notification stream)
If you'd rather not accumulate a pile of banners, a Live Activity gives you a single card on your Lock Screen that updates in place — running, needs you, done — so you can glance at a locked phone and read the current state without opening anything. See Live Activities and Dynamic Island.
Stop babysitting your terminal
Agentfy pushes Claude Code status to your iPhone — Live Activities, Dynamic Island, and instant alerts.
The multi-agent problem: which one needs me?
The moment you run more than one agent at a time, a single terminal bell falls apart — every session rings the same tone and you can't tell which one wants you. Two fixes:
- Label your alerts. Include the project or session name in the hook payload so each notification says which agent it came from.
- Give each session its own card. A phone monitor that shows every session as a separate Live Activity turns "something beeped" into "the
api-refactoragent needs a permission approval" — answerable at a glance.
Running several agents and only hooking Stop is a recipe for missed stalls: while you wait for one agent to "finish," another is quietly parked on a permission prompt. Hook the Notification event too, and label every alert.
How to actually wire it up
All of this runs through Claude Code's hook system — the Stop and Notification events are two of several you can attach commands to. If you've never touched hooks, start with the complete guide; if you set them up and nothing fires, the troubleshooting guide covers the usual culprits (wrong event, non-interactive shell, stale token).
Claude Code Hooks: The Complete Guide
Every hook event, what each one fires on, and how to attach commands to them.
If you'd rather skip the wiring, Agentfy installs the Stop and Notification hooks for you via an open-source Claude Code plugin, then pushes each session's status to your phone as a notification or a Live Activity — so "is it done yet?" is always a glance away.