Claude Code Finished? Get a Notification Automatically

Claude Code can notify you when it finishes a response, needs permission, or has been idle waiting for input. For the quickest setup, use its built-in desktop notifications in Ghostty, Kitty, or iTerm2. In other terminals, enable the terminal bell or add a Notification or Stop hook to ~/.claude/settings.json.

Use Notification with the idle_prompt matcher when you want an alert after Claude is done and waiting. Use Stop when you want an immediate alert after every completed response. The distinction matters: idle_prompt is less noisy but can be delayed, while Stop fires once per turn, including short answers.

Choose the Signal You Actually Need

If you keep forgetting to return to a long-running task, start with Stop. If that produces too many alerts, switch the completion alert to idle_prompt and keep a separate permission_prompt alert.

Prerequisites

You need a current Claude Code installation and one native notification command that works outside Claude Code.

Check the installed version:

claude --version

Then test the command for your operating system before putting it in a hook.

macOS

osascript -e 'display notification "Claude Code test" with title "Claude Code"'

Expected result: macOS shows a notification from Script Editor. If nothing appears, open System Settings, select Notifications, enable Script Editor notifications, and run the command again.

Linux

command -v notify-send
notify-send 'Claude Code' 'Claude Code test'

Expected result: command -v prints the executable path and your desktop notification service shows the message. A headless shell without a desktop session or notification bus will not display it.

Windows PowerShell

Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.MessageBox]::Show('Claude Code test', 'Claude Code')

Expected result: Windows opens a message box. Close it before continuing.

Do not configure a hook until its native command works by itself. That separates an operating-system permission problem from a Claude Code configuration problem.

Option 1: Turn On the Terminal Bell

If a sound is enough, add this top-level setting to ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Restart Claude Code after saving the file. Expected result: the terminal rings when Claude finishes a task or pauses for permission. Your terminal profile must allow the audible bell.

This is the smallest setup, but a bell cannot tell you which project needs attention when several sessions are running.

Option 2: Notify When Claude Finishes a Response

Add a Stop hook for an immediate completion alert. On macOS:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\"'",
            "async": true
          }
        ]
      }
    ]
  }
}

For Linux, replace only the command:

"command": "notify-send 'Claude Code' 'Claude Code finished'"

For Windows, use the native PowerShell hook support:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('Claude Code finished', 'Claude Code')",
            "async": true
          }
        ]
      }
    ]
  }
}

The asynchronous setting prevents a notification command from delaying Claude Code. A Stop hook does not support a matcher, so it runs after every response. If your settings file already contains hooks, merge Stop beside the existing event keys instead of replacing the whole object.

Option 3: Alert Only When Claude Is Waiting

Use the Notification event when you want fewer alerts. This macOS example separates completed work from permission requests:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Ready for your next prompt\" with title \"Claude Code\"'",
            "async": true
          }
        ]
      },
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Permission needed\" with title \"Claude Code\"'",
            "async": true
          }
        ]
      }
    ]
  }
}

Use the tested Linux or Windows command in the same structure if you are not on macOS. The idle_prompt alert waits until Claude is idle rather than firing the instant a response finishes. An open Anthropic issue documents a 60-second idle delay, so choose Stop if immediate completion timing is important.

Verify the Hook End to End

Restart Claude Code, then enter:

/hooks

Expected result: the hooks browser shows the configured event and command. The browser is read-only; edit the settings file to change the hook.

Now ask Claude to complete a harmless task, such as summarizing the current directory without editing files, and switch to another window.

• With Stop, expect an alert as soon as the response finishes.

• With idle_prompt, wait through the idle period before judging the test.

• With permission_prompt, ask Claude to propose a command that requires approval and confirm the alert appears before approving or denying it.

Finally, run Claude Code with debug output if the event appears in /hooks but the command does not run:

claude --debug

Common Failure Modes

Hooks run with your user permissions. Keep commands fixed, review them before use, and never interpolate untrusted task text into a shell command.

Send the Alert to Lark When You Leave Your Desk

A local alert solves the desktop case. For a phone or team channel, connect Lark through Aident Loadout, inspect the current send-message Action, and test one destination before wiring it into a wrapper script.

If Aident Loadout is not installed, tell Claude Code:

Follow https://aident.ai/SETUP.md

Then use this request:

Confirm my Aident Loadout account and Vault status. Find the current Lark send-message Action, inspect its input schema, and prepare one test message for the destination I name. Do not send it until I approve

Expected result: Claude identifies a current Action, shows the exact fields it needs, and waits for approval before sending. After one verified test, keep the destination and message shaping in a single reviewed script and call that script from the hook. Do not paste provider credentials into settings.json or duplicate the integration logic across several hook commands.

This follows the practical pattern behind Aident's Ollama networking guide: answer the exact problem, provide reproducible commands, show expected results, cover failure modes, and explain why the fix works. For the wider integration setup, see how to connect Claude Code and Codex to real-world tools.

Test One Completion Alert

Connect Lark through Aident Loadout, inspect the current send-message Action, and send one approved test alert. Success means the named destination receives exactly one message, the local hook still works, and no provider credential appears in your Claude settings or repository.

Why This Works

Claude Code exposes lifecycle events instead of forcing a script to scrape terminal output. Stop represents the end of a response. Notification represents a state that needs attention, and its matcher distinguishes idle, permission, authentication, and background-agent events. The hook maps one of those structured events to a native or connected notification command.

The result is a dependable handoff: Claude works, one event fires, and you return only when the session needs you.

Sources

• Claude Code hooks reference, Anthropic, accessed July 30, 2026

• Automate actions with hooks, Anthropic, accessed July 30, 2026

• Configure your terminal for Claude Code, Anthropic, accessed July 30, 2026

• Claude Code communications kit, Anthropic, accessed July 30, 2026

• Notifications for task completion and awaiting user response, Anthropic GitHub issue, opened October 18, 2025, accessed July 30, 2026

• Configurable timeout for the idle prompt notification hook, Anthropic GitHub issue, opened December 13, 2025, accessed July 30, 2026

• Aident Loadout, Aident, accessed July 30, 2026

Refresh this guide when Anthropic changes Notification matchers, the idle delay, background-agent requirements, terminal support, hook configuration, or PowerShell behavior.