Claude Code Notifications: Know When Work Needs Attention
Claude Code can alert you when a task finishes or needs a decision. Here is how notifications and hooks work, what each event means, and why task status still needs to live in an external record.
Updated 5 min read
Claude Code can notify you when a task completes or when it needs your attention, so you do not have to watch the terminal continuously. Notifications arrive through hooks — shell commands that Claude Code runs when specific events occur — or through the terminal itself, such as a bell character that triggers a sound or a visual flash.
A notification tells you something happened. It does not tell you what was done, what still needs checking, or what the next step is. Tools like fenbs keep the actual task status in a maintained record, so you can read what changed and what remains when a notification brings you back to the session.
What notification options does Claude Code have?
Claude Code supports notifications through its hooks system. Hooks are shell commands that run automatically at defined points in the session lifecycle. You configure them in Claude Code's settings file. Anthropic's Claude Code documentation (opens in a new tab) describes the available hook types and the configuration format.
On macOS, a hook can invoke osascript to display a system notification, which appears in Notification Center and can make a sound. On Linux, you can use notify-send for desktop notifications if your environment supports it. On any platform, a hook can also ring the terminal bell with printf "\a", which triggers the terminal emulator's visual or audio alert.
What events can trigger a hook?
Claude Code hooks fire at specific points in the session. Common trigger points include the end of a tool use (a file write, a shell command, or an MCP call) and the end of the assistant's response turn. You can use these to send a notification when Claude Code finishes a batch of file edits or when it returns control to you after a long task.
- Task completion. Claude Code reaches the end of an instruction and returns control. The notification lets you know it is waiting for the next prompt.
- Tool call completion. A specific tool run, such as a file write or a shell command, finishes. Useful for monitoring progress on multi-step tasks without watching every line.
- Permission required. Claude Code reaches an action that its current settings require you to approve. Without a notification, you might not realize it has stopped and is waiting.
How do you set up a notification hook?
Open Claude Code's settings file and add the hook command under the appropriate event. Keep the notification simple: a brief message that tells you which session finished, not a full task log. The task log belongs in fenbs, not in a notification.
# In ~/.claude/settings.json hooks section:
# "Stop": [{"command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'"}]Test the hook on a short task before using it for long-running work. Confirm the notification appears, that the sound or visual cue is noticeable without being disruptive, and that the hook does not interfere with Claude Code's own operation.
What should you check when a notification arrives?
A notification means the event fired, not that the work was successful. When you return to the session, read what Claude Code produced before responding or continuing. Specifically:
- What did Claude Code do? Read the last response, not just the notification message.
- Did any test or verification pass or fail? Do not assume completion means correctness.
- Is it waiting for a decision? If Claude Code stopped because it reached a choice point, that choice needs a person, not another prompt.
- Does the task status in fenbs match what the session produced? Update the task before moving on.
Why a notification is not enough for tracking work
If a task spans multiple sessions or a different person picks up the work, a notification history is not available to them. They need the task status, not the alert log. What was done, what was checked, and what remains are the facts a handoff requires.
Notifications are about the moment. Task records are about the project. The Claude Code handoff guide covers transferring the work state between sessions; notifications and hooks support the workflow but do not replace that record.
Keep the task status alongside the notification
When a notification brings you back to a session, update the fenbs task with what was done and what remains before closing the session or starting a new one. Where we left off is available to anyone who needs to continue the work, whether or not they saw the original notification.
Create a free accountFree for one person · No credit card · Works with Claude, ChatGPT, Cursor and more
How to do this with fenbs
- Create a free account and add the project your Claude Code sessions work on.
- Set up a notification hook in Claude Code's settings. Start with a simple terminal bell or system notification to confirm the hook fires correctly.
- Connect Claude Code to fenbs from Integrations. Ask it to read the project context at the start of each session.
- When a notification brings you back to the session, review what Claude Code produced and update the fenbs task status.
- Before closing the session, ask Claude Code to save progress and Where we left off. The next person or session can read the task state without relying on notification logs.
fenbs does not send notifications or integrate with Claude Code hooks. It holds the task record that you update when a notification prompts you to return. Keeping the task status current means the record is useful even when you cannot act on a notification immediately. For a broader look at how hooks work in Claude Code workflows, the hooks examples guide covers common patterns and how to combine them.