Feature request: built-in completion notifications for VS Code extension

Status Open

Maintainer reply None cached

Activity 11 comments · opened Mar 1, 2026

Problem

There's no reliable built-in way to know when Claude Code finishes working — in either the VS Code extension or the terminal CLI. The Notification hook with idle_prompt matcher — which should be the canonical "done and waiting" signal — does not fire in VS Code (documented in #8985, #11156, #16114, #28774) and has been reported as unreliable in the terminal CLI as well (#8320, closed as NOT_PLANNED). This forces users to build fragile notification systems on top of the Stop hook, which fires on every response turn, not just genuine completions.

What users are building (and why it's painful)

The community has converged on increasingly complex workarounds:

Time-based debouncing (sleep 3s, check if another Stop fires) — arbitrary, unreliable
Transcript JSONL parsing in Stop hooks to find recent tool_use timestamps and suppress mid-loop notifications
Shared cooldown files between Stop and TaskCompleted hooks to prevent double-tap notifications during agent team runs
Regex content filters on last_assistant_message — fragile, can't anticipate every mid-workflow message
LLM-as-classifier via type: "prompt" Stop hooks — adds latency and API cost per turn

Multiple repos exist just to solve this: ADAPT-Chase/claude-stop-hook, felipeelias/claude-notifier, dazuiba/CCNotify, wyattjoh/claude-code-notification. The OpenCode ecosystem has 3+ competing notification plugins. This is a gap in the core product.

Terminal CLI — additional pain points

For terminal users (our primary environment), the problems are compounded:

No AskUserQuestion tool in CLI mode. When Claude has a question, it just outputs text ending with ? and the Stop hook fires. There's no distinct signal — you have to regex-match the last line to guess if it's a question vs a statement. The VS Code extension has the AskUserQuestion PreToolUse hook for this, but terminal users get nothing.
Notification:idle_prompt was closed as NOT_PLANNED (#8320) for the terminal CLI. The 60-second idle timeout never fires. This means terminal users have zero first-class "Claude is done" signals — only the noisy Stop hook.
No native terminal notification integration. Users must install third-party tools (terminal-notifier, notify-send) and wire them up manually. Other CLI tools like Aider have --notifications as a built-in flag that auto-detects the platform and sends native notifications. Claude Code could do the same.
Agent team runs are especially noisy in terminal. With TaskCompleted and Stop both firing in rapid succession, and no visual distinction between a teammate status update and a genuine "I need your input" moment, terminal users end up building dedup logic with cooldown files just to avoid notification spam.
Bell character (\a) would be a zero-dependency option. Many terminal emulators (iTerm2, kitty, WezTerm, Windows Terminal) can be configured to show a notification or bounce the dock icon on bell. Emitting \a when Claude genuinely finishes would require zero user setup and work across all platforms.

Proposed solution

Fix Notification:idle_prompt everywhere. Make it fire reliably in both the VS Code extension and the terminal CLI. This is the most impactful single change — the hook exists, the payload is designed, it just doesn't fire. If it worked, most of the workaround ecosystem would be unnecessary.

Add a completion_type field to the Stop hook payload that distinguishes:

"end_turn" — Claude finished and is waiting for user input (genuine idle)
"tool_pause" — Claude paused between tool calls in an agentic loop
"agent_update" — a teammate/subagent sent a status update

This single field would eliminate the need for transcript parsing, debouncing, and cooldown files.

Built-in --notify flag for the CLI (like Aider's --notifications). Auto-detect platform, send native notification when Claude finishes or needs input. No hooks, no third-party tools. For terminal users this would be the simplest path.

Emit bell character (\a) on genuine completion. Zero-dependency, works with existing terminal emulator notification features (iTerm2 dock bounce, tmux monitor-bell, etc.). Could be behind a --bell flag or a setting.

Built-in notification support in the VS Code extension — a simple toggle in settings that sends a native VS Code notification when Claude finishes or needs input. No hooks, no scripts, no terminal-notifier. Cursor's community has been requesting this too (forum threads #32835, #56793, #100843).

Give terminal CLI a distinct signal for questions. Either fire a specific hook event when Claude's response ends with a question/prompt for the user, or add a needs_input boolean to the Stop hook payload. Currently terminal users have to regex-guess from last_assistant_message.

Environment

Claude Code terminal CLI (primary) and VS Code extension
macOS (but the Notification hook bug also affects Linux per #8320)
Using agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)

View original on GitHub ↗

11 Comments

github-actions[bot] · 6 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

m-prokofiev · 6 months ago

Adding a JetBrains/IntelliJ IDEA perspective to this, since the issue covers VS Code but the same problem applies to the JetBrains plugin.

Environment: Claude Code [Beta] JetBrains plugin, IntelliJ IDEA, macOS

Problem: When Claude is waiting for user input/tool approval in IntelliJ's embedded terminal, no notification is delivered. Root cause: macOS only delivers the OS-level
notification when the terminal loses focus, but in an embedded terminal the IDE (IntelliJ IDEA) remains the foreground app — so the focus-loss trigger never fires.

This can be confirmed by manually cmd+Tab away from IntelliJ after Claude starts waiting — the notification then arrives. The OS notification channel itself works fine
(osascript test passes, Focus mode is off).

What would help: Either of the proposals in this issue would solve it for JetBrains users too — particularly the Notification:idle_prompt hook fix, the bell character option
(\a), or IDE-native notifications via the JetBrains plugin API (equivalent to what's proposed for VS Code). The bell character approach is especially appealing since IntelliJ
can be configured to respond to terminal bell with a visual/audio signal.

VIKI623 · 5 months ago

+1 — I’m mainly on the VS Code extension (macOS) and the lack of basic “task finished / needs input” signals is rough, especially when the extension already trails the CLI in features. Without a proper notifier or richer hooks I’m stuck babysitting runs and hacking together scripts just to stay in sync. Would love to see the extension catch up here.

janpaepke · 5 months ago

For terminal CLI users on Ghostty/macOS: I built haunt, which sidesteps the hook reliability problem entirely. It detects Claude Code's working/idle state from the terminal title prefixes (✳ for idle, braille spinner for working) and tracks the transitions — so when Claude goes from working→idle on a background tab, it highlights that tab as needing attention. There's a --next hotkey to jump straight to whichever session needs your input.

It's not a general solution (Ghostty + macOS only), but for that setup it works reliably without any hook configuration.

yurukusa · 5 months ago

A Stop hook can send desktop/VS Code notifications when Claude finishes:

printf '\a'
notify-send "Claude Code" "Response complete" 2>/dev/null
osascript -e 'display notification "Response complete" with title "Claude Code" sound name "Glass"' 2>/dev/null
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > /tmp/cc-completed
exit 0

For VS Code, you can also use the terminal bell approach combined with a VS Code setting:

// .vscode/settings.json
{
    "terminal.integrated.enableBell": true
}

The printf '\a' in the Stop hook will then trigger a visual or audio notification in VS Code's terminal whenever Claude finishes.

yurukusa · 5 months ago

A Stop hook can send completion notifications:

printf '\a' >&2
if [ "$(uname)" = "Darwin" ]; then
    osascript -e 'display notification "Claude Code finished" with title "Claude Code" sound name "Ping"' 2>/dev/null
elif [ -n "$WSL_DISTRO_NAME" ]; then
    powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code finished','Done')" 2>/dev/null &
else
    notify-send -u normal "Claude Code" "Task complete" 2>/dev/null
fi
exit 0

{
  "hooks": {
    "Stop": [{
      "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/completion-notify.sh" }]
    }]
  }
}

Works across macOS (notification center), Linux (notify-send), WSL (Windows message box), and any platform (terminal bell). Add ntfy.sh for phone notifications.

ShunmeiCho · 5 months ago

Great writeup on the notification gaps. For the SSH-specific part of this problem, I've been working on a notification bridge in cc-clip that uses Claude Code's hook system to forward events through an SSH reverse tunnel to a local daemon.

It covers the Stop (task complete) and Notification (permission prompt, idle) hooks — the events that matter most when you step away from the terminal. Delivery goes through macOS Notification Center or cmux if available.

Not a replacement for proper built-in notification support, but it works as a stopgap for remote/SSH sessions where OSC and terminal bell aren't reliable.

yuhualu-cpu · 3 months ago

Claude Code in VSCode asked me to open a ticket but looks like this is the ticket already opened, looking forward to having this feature, would be big time saver for me

tristan666666 · 2 months ago

Another external workaround for macOS users who want a persistent visual signal rather than one-shot notifications: I built Agent Island as a small notch-level status layer for Claude/Codex sessions.

It tries to make the distinction this issue is asking for visible at a glance:

running -> logo breathes
waiting for you -> logo spins
stuck/interrupted -> logo turns red + beeps

It can also auto-resume a selected long-running session when it is able to continue again. Not a replacement for proper built-in Claude Code hooks/notifications, but useful if the main pain is babysitting long sessions on macOS.

https://github.com/tristan666666/agent-island

tredondo · 2 months ago

@saurabhav88

There's no reliable built-in way to know when Claude Code finishes working — in either the VS Code extension

Would it be worth updating the OP given there's no reliable built-in mechanism to signal that Claude Code needs any user input (e.g. tool permissions, AskUserQuestion, exceeding quota), not just having finished working?

More quasi-duplicate issues:

https://github.com/anthropics/claude-code/issues/31178 (auto-closed by the bot)
https://github.com/anthropics/claude-code/issues/57230 (14 upvotes)
https://github.com/anthropics/claude-code/issues/65241 (another dupe that should be merged, maybe @szwang can help)

crisdesivo · 1 month ago

Any update on this?