Claude Notify

Remote Pushover notifications for Claude Code sessions. Get notified on your phone when Claude finishes work or waits too long for your input.

For local sound notifications, use peon-ping.

Install

bunx @lekman/claude-notify

This installs the hook script, /remote-notify skill, and Claude Code settings. The installer prompts for scope:

• Workspace (default) — installs to .claude/ in the current project
• User — installs to ~/.claude/ for all projects

Skip the prompt with --scope:

bunx @lekman/claude-notify --scope=workspace
bunx @lekman/claude-notify --scope=user

CLI commands

| Command | Description | | ----------- | ------------------------------------------------------------------ | | install | Install hooks, skill, and settings (default when no command given) | | uninstall | Remove hooks, skill, and settings from both workspace and user | | test | Send a test Pushover notification | | configure | Set GitHub repo secrets for the Claude Code Actions workflow |

The install command is implicit — bunx @lekman/claude-notify --scope=user and bunx @lekman/claude-notify install --scope=user are equivalent.

From a local clone

git clone https://github.com/lekman/claude-nofity
cd claude-nofity
bun install && bun run build
bun run claude-notify

Setup

You need two values from pushover.net. Add them as environment variables or in a .env file at the project root:

PUSHOVER_USER_KEY="your-user-key"
PUSHOVER_APP_TOKEN="your-app-token"

Where to find these

1. PUSHOVER_USER_KEY — Log in to pushover.net. Your User Key is displayed at the top of the dashboard, labeled "Your User Key". This identifies your account as the notification recipient.

2. PUSHOVER_APP_TOKEN — On the same dashboard, scroll to "Your Applications" and create a new application (or use an existing one). The API Token shown on the application page is your app token.

Both values are 30-character alphanumeric strings and look similar — make sure you don't mix them up.

Pushover app icon

When creating your Pushover application, you can upload a custom icon so notifications are easy to identify. A suggested icon is included as:

• Monochrome
• Colour

Upload it under Your Applications > your app > Icon on pushover.net.

Optional

CLAUDE_NOTIFY_TIMEOUT_SECONDS=120       # idle timeout before notification (default: 120)
CLAUDE_NOTIFY_RATE_LIMIT_SECONDS=30     # minimum seconds between notifications (default: 30)
CLAUDE_NOTIFY_LABEL=my-workstation      # optional label appended to messages (default: none)
CLAUDE_NOTIFY_ENABLED=true              # always on, bypasses session toggle (for CI)

Usage

Remote notifications are off by default. Toggle them on for the current session:

/remote-notify

This writes a session flag file. When enabled, all 4 hook events send Pushover notifications. When disabled (or on a new session), hooks exit silently.

To always enable without toggling (e.g., in CI or Codespaces), set CLAUDE_NOTIFY_ENABLED=true in your environment.

Test

bun .claude/hooks/claude-notify.js test

How it works

Four Claude Code hooks fire at different points in a session:

| Hook Event | Mode | What happens | | ------------------ | -------------- | -------------------------------------------------- | | Notification | notification | Push notification when Claude is waiting for input | | Stop | stop | Push notification when Claude finishes work | | UserPromptSubmit | arm | Starts an idle timer after you send a prompt | | SessionStart | reset | Clears any pending idle timer |

If you don't respond within the idle timeout (default 120s), you get a notification.

The hook script uses fetch() to call the Pushover API directly — no npm dependencies needed in the target project. Bun auto-loads .env files.

Uninstall

bunx @lekman/claude-notify uninstall

Removes hooks, skill, and settings entries from both workspace and user locations.

GitHub Actions / Codespaces

A Claude Code Action workflow is included at .github/workflows/claude.yml. It triggers when @claude is mentioned in issues or PR comments, and runs with Pushover notifications enabled via hooks.

The workflow installs Bun before running Claude so that the bun-based hooks work in CI. Set CLAUDE_NOTIFY_ENABLED=true in the workflow env to bypass the session toggle.

Actions Setup

1. Go to your repo Settings > Secrets and variables > Actions
2. Add these repository secrets:

| Secret | Required | Description | | ------------------------- | -------- | --------------------------- | | CLAUDE_CODE_OAUTH_TOKEN | Yes | OAuth token for Claude Code | | PUSHOVER_USER_KEY | Yes | Your Pushover user key | | PUSHOVER_APP_TOKEN | Yes | Your Pushover app token |

3. Notifications are sent whenever Claude finishes work or waits for input — the environment label shows "Codespaces" when running in Codespaces, or the machine hostname otherwise.

Development

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.