claude-pager — Claude Code plugin: alerts and setup
claude-pager shows desktop alerts when Claude Code needs approval, input, or has finished a task. Useful for sessions you are not watching constantly.
MIT ★ 3,785 updated 2026-10-25
/plugin marketplace add davepoon/buildwithclaude
/plugin install claude-pager@buildwithclaudeWhat claude-pager does
claude-pager sends a native notification when Claude Code asks to approve a tool, waits for your input, or completes its work. The project name appears in the notification title, so you can identify the session that needs attention.
Each event can use its own sound or be muted with none. Options live under pluginConfigs in ~/.claude/settings.json, where you can turn permission, idle, and completion alerts on or off. On Linux, desktop alerts depend on the libnotify package and notify-send.
macOS uses terminal-notifier or osascript, Linux uses notify-send, and Windows uses a PowerShell notification balloon. Over SSH or without a desktop, the plugin writes a line to stdout and rings the terminal instead. It requires Claude Code v2.1.0+; Node.js comes with Claude Code.
What it helps with
- notice when tool approval is needed
- see that Claude Code is waiting for input
- track task completion away from the terminal
- identify the project behind an alert
Example prompts for the agent
- Run the task and ask for approval before changing files.
- Wait until the current task finishes, then report the result.
- Pause before the next step and wait for my reply.
How to install claude-pager
Plugin marketplace
/plugin marketplace add davepoon/buildwithclaude/plugin install claude-pager@buildwithclaudeStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about claude-pager
How do I install claude-pager in Claude Code?
Run /plugin marketplace add davepoon/buildwithclaude, then run /plugin install claude-pager@buildwithclaude.
What does claude-pager do?
It shows desktop notifications when Claude Code requests tool approval, waits for input, or finishes a task. The project name is included in the alert title.
What does claude-pager need on Linux?
Desktop alerts require the libnotify package and notify-send. Without a desktop session, it falls back to stdout and a terminal bell.
Source text
claude-pager · MIT
<h1 align="center"><img src="https://i.ibb.co/jPRMBm30/icon.jpg" alt="claude-pager icon" width="36" height="36" align="center"> Claude Pager</h1>
<p align="center">Native desktop notifications for Claude Code. Get alerted when a session needs your attention — permission prompts, idle waits, or task completion.</p>
## Install
```bash
git clone https://github.com/bharat7gupta/claude-pager.git
claude --plugin-dir ./claude-pager
```
## What It Does
Each notification shows your **project name** in the title so you know which session to switch to.
### Permission — Claude needs tool approval
<img src="https://i.ibb.co/QFRXF8w8/permission.webp" alt="Permission notification" width="500">
### Idle — Claude is waiting for your input
<img src="https://i.ibb.co/nNxn5GzD/idle.png" alt="Idle notification" width="500">
### Task Completion — Claude finished working
<img src="https://i.ibb.co/WNTYt00M/task-completion.webp" alt="Task completion notification" width="500">
<img src="https://i.ibb.co/Jw5xWwCX/task-completion-2.jpg" alt="Task completion notification with summary" width="500">
## Configuration
After install, configure via `pluginConfigs` in `~/.claude/settings.json`:
```json
{
"pluginConfigs": {
"claude-pager": {
"options": {
"idle_enabled": "on",
"permission_enabled": "on",
"completion_enabled": "on",
"idle_sound": "default",
"permission_sound": "default",
"completion_sound": "default"
}
}
}
}
```
### Toggle Events
Set any `*_enabled` to `"off"` to disable that notification type.
### Sound Presets
| Preset | Description |
|---|---|
| `default` | Per-event default (idle=blow, permission=funk, completion=glass) |
| `blow` | Warm, noticeable |
| `funk` | Short, attention-grabbing |
| `glass` | Satisfying ding |
| `ping` | Subtle ping |
| `pop` | Quick pop |
| `hero` | Bold alert |
| `none` | Silent — visual notification only |
## Platform Support
| Platform | Notification | Sound | Notes |
|---|---|---|---|
| **macOS** | `terminal-notifier` or `osascript` | `afplay` | Works out of the box. `brew install terminal-notifier` for clickable notifications |
| **Linux** | `notify-send` | `paplay` / `aplay` | Requires `libnotify` package |
| **Windows** | PowerShell NotifyIcon balloon | PowerShell SystemSounds | Optional: install `BurntToast` module for modern toasts |
### Headless / SSH
When no desktop is available, falls back to a stdout line + terminal bell. No errors.
## Requirements
- Claude Code v2.1.0+
- Node.js (ships with Claude Code)
- Linux: `libnotify` / `notify-send` for desktop notifications
## License
MIT
© Bharat Gupta · MIT · davepoon/buildwithclaude