Agent Ping

Plays a sound when Claude finishes responding, asks a question, or needs your permission — so you can step away and come back when needed. Works with VS Code and any VS Code-based editor (Cursor, Windsurf, etc.).

⚠️ This extension is deprecated. Agent Ping is now a Claude Code plugin that works across CLI, desktop app, and all editors — no extension needed. Migrate to the plugin →

Install

Editor extension

Open the Extensions panel (Cmd+Shift+X / Ctrl+Shift+X) and search for Agent Ping, or install from the Visual Studio Marketplace.
Install the CLI so Claude's hooks can trigger sounds:
```
npm i -g agent-ping-vscode
```
Reload your editor. Sounds will play automatically — no further setup needed.

The extension manages your settings and sound preferences. The CLI is what actually plays the sounds when Claude triggers a hook — it needs to be installed globally so the hooks can find it. If the CLI is missing, the extension will show a warning with a Retry button.

CLI only

If you use Claude Code in a terminal without an editor, you only need the CLI:

npm i -g agent-ping-vscode

Sounds will play automatically after the next time Claude runs. To configure settings interactively, run:

agent-ping-vscode config

See CLI-only configuration for more options.

Updating

Updates are automatic via the Marketplace. Reload your editor after updating.

To update the CLI, run npm i -g agent-ping-vscode again.

Uninstall

Remove hooks and config:
```
agent-ping-vscode uninstall
```
Remove the extension from the Extensions panel, or from the command line:
```
<editor> --uninstall-extension dawi.agent-ping-vscode
```
Remove the CLI:
```
npm uninstall -g agent-ping-vscode
```

Settings

Open your editor settings (Cmd+, on Mac, Ctrl+, on Windows) and search for Agent Ping.

Setting	Description	Default
Enabled	Enable or disable Agent Ping entirely	On
Alert Mode	Play a sound, show an OS notification banner, or both	Sound
Respect DND	Suppress sounds when any macOS Focus mode is active (notification banners are managed by macOS). Requires macOS accessibility permissions on first use.	Off
Volume	Global volume for all sounds (0 = mute, 100 = full volume)	50
Notification Enabled	Enable or disable the Notification event sound	On
Notification Sound	Custom sound file for notifications (WAV, MP3, AIFF)	Bundled default
Idle Prompt Enabled	Play the notification sound when Claude is waiting for input	Off
Stop Enabled	Enable or disable the Stop event sound	On
Stop Sound	Custom sound file for the stop event (WAV, MP3, AIFF)	Bundled default

Each sound setting has a Choose file... link to pick a file, Test sound to preview, and Reset to default to go back to the bundled sound.

CLI-only configuration

If you use the CLI without the editor extension, you can customize settings in ~/.agent-ping-vscode/config.json:

{
  "enabled": true,
  "alertMode": "sound",
  "respectDnd": false,
  "volume": 50,
  "notificationEnabled": true,
  "notificationSound": "",
  "idlePromptEnabled": false,
  "stopEnabled": true,
  "stopSound": ""
}

Leave sound paths empty to use the bundled defaults, or set an absolute path to a WAV, MP3, or AIFF file.

You can also override sounds and volume via environment variables in ~/.claude/settings.json:

{
  "env": {
    "AGENT_PING_STOP_SOUND": "/Users/yourname/Sounds/done.wav",
    "AGENT_PING_NOTIFICATION_SOUND": "/Users/yourname/Sounds/ping.wav",
    "AGENT_PING_VOLUME": "50"
  }
}

Environment variables take precedence over the config file. When the editor extension is running, it manages the config file — use the editor's settings panel instead.

Platform notes

Note: Agent Ping is developed and tested on macOS. Linux and Windows support is provided on a best-effort basis and has not been thoroughly tested. Bug reports and pull requests are welcome.

Platform	How sound plays	Volume control	Notification banners	Focus / DND
macOS	`afplay` — built in, nothing extra needed	Supported	Native editor notification when extension is running; `osascript` fallback for CLI-only (attributed to Script Editor)	Supported — sounds suppressed during any Focus mode; banners filtered by macOS per your Focus settings
Windows	PowerShell — built in, nothing extra needed	Not supported — uses system volume	Native editor notification when extension is running; PowerShell toast fallback for CLI-only	Not supported
Linux	Requires `paplay` (PulseAudio) or `aplay`	`paplay` supported, `aplay` uses system volume	Native editor notification when extension is running; `notify-send` fallback for CLI-only (with app icon)	Not supported

Migrating from the VS Code extension

Agent Ping is now available as a Claude Code plugin with cross-platform support. To migrate:

Install the plugin:

/plugin marketplace add DavidWilsby/agent-ping
/plugin install agent-ping

The plugin automatically copies your settings and removes the old hooks on first run
Uninstall the old extension:
- VS Code: code --uninstall-extension dawi.agent-ping-vscode
- Cursor: cursor --uninstall-extension dawi.agent-ping-vscode
- Windsurf: windsurf --uninstall-extension dawi.agent-ping-vscode
Optionally remove the global npm package: npm uninstall -g agent-ping-vscode

Troubleshooting

No sound plays — Check your system volume. Open editor settings (Cmd+,) and search Agent Ping — make sure Enabled is on and the relevant event (Notification or Stop) is also enabled. If you set a custom sound path, make sure the file exists at that exact location.

Wrong sound plays — Open editor settings and search Agent Ping to review which sound is set for each event.

Test it — Ask Claude "What is 2 + 2?" — you should hear the stop sound when it replies.

Security

This extension modifies ~/.claude/settings.json to register Claude Code hooks — this is how it knows when to play sounds. The hooks call the agent-ping-vscode binary with event names (stop, notification). No data is sent externally. The extension also writes a lock file and event file to ~/.agent-ping-vscode/ for coordination between the editor and CLI.

Socket.dev flags this as medium risk because it sees settings.json modification and command execution. This is expected and necessary behavior for a Claude Code hook integration.

Agent Ping for Claude

DAWI