claude-pulse

claude-pulse

claude-pulse is a Claude Code plugin that delivers native macOS notifications at the end of every session turn. It detects whether Claude performed actual work (tool use) or simply replied, and adjusts the notification body accordingly. Notification titles display your session name rather than a raw UUID.

Features

• Session-aware titles — resolves your named session from ~/.claude/sessions/*.json; falls back to the working directory name or the first 8 characters of the session ID
• Task/reply detection — shows Task completed when tool use occurred in the turn, Replied when Claude only sent text
• Attention alerts — a Needs your attention notification fires only for user-actionable Claude Code events (permission_prompt, elicitation_dialog); informational events such as idle_prompt and auth_success are silently ignored
• Failure alerts — if a turn terminates because of an API error (rate limit, auth failure, billing issue, server error, truncated output, etc.) claude-pulse surfaces a concise macOS notification instead of leaving you to discover the failure in the terminal
• Working-directory alerts — when Claude's Bash tool changes the session's working directory you get a notification showing the new directory, so you never silently end up editing in an unexpected place
• Subagent completion alerts — when a subagent spawned by the Agent tool or a team-orchestration skill finishes, claude-pulse pings you with the agent type so you know when to come back to a long-running delegation
• Namespaced temp files — marker files are written to $TMPDIR/claude-pulse-last-input-* to avoid collisions with other tools

Requirements

• macOS — this plugin is macOS-only. Notifications are delivered through osascript, which ships with macOS by default.
• jq (optional but recommended) — enables accurate task/reply detection. Without it, every turn is reported as Replied.

Install jq via Homebrew:

brew install jq

Installation

/plugin marketplace add https://github.com/DokaDev/claude-pulse
/plugin install claude-pulse@claude-pulse

No further setup is required — the plugin registers its hooks automatically on install.

Updating

To pull in a new release after the marketplace has been updated upstream, run the following three commands from any Claude Code session:

/plugin marketplace update claude-pulse
/plugin update claude-pulse@claude-pulse
/reload-plugins

The first command refreshes the marketplace catalogue so Claude Code sees the new version. The second command replaces the installed plugin files in the local cache. The third command reloads every plugin in the current session without requiring a restart.

How It Works

1. UserPromptSubmit — track-user-input.sh writes the current UTC timestamp to $TMPDIR/claude-pulse-last-input-{session_id} whenever the user submits a real prompt.
2. Stop — notify-done.sh reads the marker timestamp and scans the transcript for any assistant entries after that point that contain tool_use content blocks.
   • One or more tool_use blocks found → Task completed
   • None found, or marker absent, or jq unavailable → Replied
3. Notification — notify.sh inspects the notification_type field on the incoming payload and fires Needs your attention only for user-actionable events (permission_prompt, elicitation_dialog). Informational events (idle_prompt, auth_success) exit silently.
4. StopFailure — notify-fail.sh reads the error_type field and delivers a short, human-readable body (Rate limited, Auth failed, Billing issue, Invalid request, Server error, Output truncated, or Turn failed for anything unrecognised).
5. CwdChanged — notify-cwd.sh reads the new cwd from the payload and sends a Working dir → <basename> alert so agent-driven directory changes never slip past you.
6. SubagentStop — notify-subagent.sh reads the agent_type field and fires Subagent done: <agent_type> (or plain Subagent done when the field is empty) so long-running delegations to subagents surface immediately on completion.

All six hooks resolve the session name through the same priority chain: named session file → cwd basename → session ID prefix, and the resolution logic lives in a single shared library at hooks/lib/session-name.sh. Notifications are delivered via osascript calling a small AppleScript helper at hooks/lib/show-notification.applescript.

A note on notification grouping

Because this plugin uses osascript for delivery, macOS groups all notifications under Script Editor in Notification Centre. Achieving a dedicated "claude-pulse" identity requires a signed, registered .app bundle, which is out of scope for this release. If that matters to you, follow the repository for future updates.

Configuration