npm package: @lekman/claude-notify
Description: Pushover notifications for Claude Code sessions
Author: Tobias Lekman
Latest version: 0.1.2

# 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](https://github.com/lekman/peon-ping).

## Install

```bash
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`:

```bash
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

```bash
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](https://pushover.net). Add them as environment variables or in a `.env` file at the project root:

```bash
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](https://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`](docs/assets/pushover-icon.png)
- [`Colour`](docs/assets/pushover-icon-color.png)

Upload it under Your Applications > your app > Icon on [pushover.net](https://pushover.net).

### Optional

```bash
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

```bash
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

```bash
bunx @lekman/claude-notify uninstall
```

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

## GitHub Actions / Codespaces

A [Claude Code Action](https://github.com/anthropics/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](docs/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.