Last updated 13 October 2026
Get desktop alerts for Claude Code tasks
The challenge of waiting for background tasks
You start a complex refactoring task with Claude Code. You see the agent begin to use the Grep tool to find usages across a massive repository. Then it uses the Read tool to understand the context of dozens of files. You know this process will take several minutes because the codebase is large and the logic is intricate. You switch to your browser to check documentation or open another terminal tab to handle a different bug. Time passes and you forget the agent was even running because your mind has moved on to other problems. This loss of momentum is a common hurdle for developers who use autonomous agents.
Waiting for a terminal process is a passive activity that drains focus and invites distraction. You need a way to stay informed about the progress of your background work without having to stare at a spinning cursor or a wall of scrolling text. Standard terminal notifications often fail when an agent is running in an interactive session because they are tied to the shell exit code rather than the internal state of the conversation. You want a system that taps into the internal lifecycle of the agent so you get an alert precisely when the work is finished and the agent is waiting for your next instruction.
The hook system mechanism in Claude Code
Claude Code provides a native way to run local shell scripts during specific lifecycle events. These are defined as hooks in your configuration. You can find information about the current state of these triggers by running the /hooks command inside any active session. The agent looks for these configurations in your settings files. You can use ~/.claude/settings.json to define hooks that apply to every project on your machine, or you can use .claude/settings.json inside a specific repository root for project-specific behavior. This flexibility allows you to customize how your environment reacts to the agent.
Hooks run as standard shell commands on your local machine. They have access to your environment but do not interfere with the logic of the agent unless the command fails in a way that blocks the process. When an event happens, the agent executes the string you provided in the settings file. This string can be a direct terminal command or a path to a dedicated shell script. Using a script file is usually the better approach because it keeps your JSON configuration file clean and makes it easier to manage complex logic like platform-specific notification sounds or varying urgency levels.
Choosing the Stop hook event for alerts
The Stop hook event is the most reliable choice for building a completion alert. This event fires whenever the agent finishes its current sequence of tool uses and returns control back to you. It happens after the agent has used tools like Write or Edit to modify your files and has finished generating its final summary of the work performed. If you use the Task tool to track a larger goal, the Stop event still signals that the immediate interactive turn is over. This is the exact moment when you need to be pulled back into the terminal to review the changes or provide the next prompt.
Other events like PreToolUse or PostToolUse fire far too often for general desktop notifications. You do not want your computer to ping every single time the agent uses the Read tool to check a file or the Glob tool to list a directory. That would create a constant stream of noise that destroys your concentration. The Stop event is discrete and meaningful. It marks the transition from the agent working to the agent waiting. By focusing on this specific transition, you ensure the notification remains a useful signal rather than background distraction that you eventually learn to ignore.
Creating the notification script
You need a small script that handles the actual desktop alert on your operating system. On macOS, you can use the osascript utility to trigger a system-level notification. A command like osascript -e 'display notification "Task complete" with title "Claude Code"' is effective. On Linux systems, the notify-send utility is the standard way to send a message to the desktop environment. Windows users can use a small PowerShell snippet to show a toast notification. You should save this script in a known location such as a scripts folder in your home directory to keep it accessible for all your projects.
Make sure your script is executable before you try to use it. On Unix-based systems, use the chmod +x command followed by the path to your script. It is a good practice to test the script manually from your terminal first. If you can run the script and see a notification appear on your desktop, then you know the script is ready for the agent to use. This separation of concerns makes it much easier to debug issues later. If the alerts stop appearing after a system update, you only have to check your script rather than your entire Claude Code configuration.
When writing your script, consider adding a sound effect to the visual alert. Visual notifications can be missed if you are looking at another monitor or if your system hides alerts while you are in a full-screen application. Adding a subtle audio cue ensures that you are aware of the task completion even if your eyes are not on the screen. Most notification utilities have flags to enable default system sounds, or you can use separate commands like afplay on macOS or paplay on Linux to trigger a specific audio file after the notification is sent.
Configuring the settings file for hooks
Open your ~/.claude/settings.json file to apply this alert globally. You need to add a top-level key named hooks. Inside that object, you add a key for the Stop event. The value should be the absolute path to the script you created in the previous step. If your script is located at /Users/username/scripts/notify.sh, your JSON entry will point exactly to that file. Ensure that the JSON remains valid after your edits by checking for trailing commas or missing quotes which can prevent the agent from loading your custom settings.
If you prefer project-specific alerts, use the .claude/settings.json file in your project root instead. This is useful if a particular project is slow and requires a more intrusive alert while your other work stays quiet. You can also pass arguments to your script within the settings file. For example, you could pass the name of the current directory as an argument. This allows your script to show which project is calling for attention, which is helpful when you have multiple terminal windows open for different repositories at the same time.
Visual management with adhdTerminal tiles
While shell hooks provide useful audio or desktop alerts, they do not help you see the detailed state of many concurrent tasks at once. This is where adhdTerminal becomes a helpful addition to your developer setup. It runs many Claude Code sessions side by side, with each one appearing as a tile on a wall. Every tile shows whether it is currently working, waiting for you, or idle. You can see the last few exchanges of the conversation directly on the tile without having to switch tabs or scroll back through a single terminal window to find where you left off.
The app is a native client for macOS and Windows that allows you to name each tile and assign it a color. When you have multiple refactoring tasks happening across different microservices, a desktop notification tells you that something is done, but the adhdTerminal wall tells you exactly which one it is at a glance. You can see headlines and numbers that the project publishes directly on the tile interface. This combination of shell hooks for immediate alerts and a visual wall for state management keeps your workflow organized and reduces the mental load of tracking several background agents.
Permissions and interaction modes
The behavior of your hooks does not change based on your permission mode, but the frequency of the alerts will. If you are in bypassPermissions mode, the agent will run through a long sequence of tool calls without stopping for your approval. Your Stop hook will fire only when the entire sequence is complete and the agent is ready for a new prompt. This is the ideal setup for long migrations or complex code generations where you want to walk away and return only when the final result is ready for review.
In the default or plan modes, you might be interacting with the agent more frequently to approve specific tool uses. You can use the Shift+Tab shortcut to cycle through these modes inside a session. If you find the notifications are firing too often because you are manually approving every Edit tool use, you might want to adjust your notification script. You could add logic to the script to check how much time has passed since the last alert was sent. This prevents a flood of notifications when you are working closely with the agent on a series of small, rapid changes.
Remote monitoring and mobile alerts
If you work across multiple machines or need to step away from your desk, you can still stay updated on your task progress. The adhdTerminal system includes a free iPhone app that mirrors your wall over an end-to-end encrypted link. When a tile on your computer changes its state to waiting, the mobile app can notify you. This means your shell hooks and your visual wall work together to keep you updated whether you are in front of your monitor or in another room. You no longer have to worry about a long-running task finishing without you noticing.
The iPhone app also allows you to interact with the sessions remotely. You can answer a prompt or send the next task directly from your phone. This is particularly useful when the agent reaches a point where it needs a simple decision that does not require you to write complex code. You can see the status of the session on your phone, see that the agent has finished its current task, and give it the go-ahead for the next step. This turns a long-running background process into a flexible system that fits into your day instead of keeping you tethered to your desk.
Questions people ask
Can I use hooks to trigger other Claude Code tools automatically?
Hooks are designed to run local shell commands for side effects like notifications, logging, or sound alerts. They do not have a direct interface to trigger internal agent tools like Edit or Write. If your script modifies a file, the agent will see those changes the next time it uses a tool like Read or Glob, but it will not react to them automatically the moment the hook finishes.
Why is my notification script not firing after I updated my settings?
The most common reason for a hook failing to fire is an incorrect file path or missing executable permissions on the script. Verify the path in your settings.json is absolute and run chmod +x on the script file. You should also check the /hooks command inside a session to see if your custom hook is listed; if it is missing, your JSON file might have a syntax error that prevented the agent from loading the new configuration.
Does the Stop hook fire if I interrupt the agent with the Escape key?
The Stop hook event typically fires when the agent reaches a natural stopping point and is ready for the next user prompt. If you manually interrupt the agent by pressing the Escape key, it stops the current tool use immediately. Depending on the timing of the interruption, the Stop event may still fire as the agent returns to the interactive prompt, but using Ctrl+C to force-quit the terminal session will usually prevent hooks from executing.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.