GitHub - quantthieres/ping-claude-balloon: Desktop notification bubble for Claude Code and terminal coding agents

██████╗ ██╗███╗  ██╗ ██████╗   ██████╗   ████╗ ██╗     ██╗      █████╗  █████╗ ███╗  ██╗
██╔══██╗██║████╗ ██║██╔════╝   ██╔══██╗██╔══██╗██║     ██║     ██╔══██╗██╔══██╗████╗ ██║
██████╔╝██║██╔██╗██║██║   ██╗  ██████╦╝███████║██║     ██║     ██║  ██║██║  ██║██╔██╗██║
██╔═══╝ ██║██║╚████║██║   ██╗  ██╔══██╗██╔══██║██║     ██║     ██║  ██║██║  ██║██║╚████║
██║     ██║██║ ╚███║╚██████╔╝  ██████╦╝██║  ██║███████╗███████╗╚█████╔╝╚█████╔╝██║ ╚███║
╚═╝     ╚═╝╚═╝  ╚══╝ ╚═════╝   ╚═════╝  ═╝  ╚═╝╚══════╝╚══════╝ ╚════╝  ╚════╝ ╚═╝  ╚══╝

Ping Balloon — desktop notification bubble for terminal coding agents.

A floating bubble that sits in the corner of your screen and tells you when Claude finishes a task or needs your approval. The bubble is hidden by default — it only appears when something actually requires your attention.

State	Colour	Behaviour
complete	Green	Appears, plays a short sound, auto-hides after 6 s
permission	Amber	Appears, plays a sound, stays visible until you act
waiting	Blue	Hidden by default — debug/optional (see Environment Variables)

Clicking the bubble brings your terminal or editor back into focus, then hides the bubble.

Quick Start

1. Install from npm

npm install -g @quantthieres/ping-balloon@latest

Verify the installation:

ping-balloon help
ping-balloon doctor

2. Start Ping Balloon

ping-balloon start

This starts the app. The window opens but the bubble stays hidden until an event arrives — no visible clutter while you work. Keep this terminal open for as long as you want to receive notifications.

3. Test manually

In a second terminal:

ping-balloon health                    # confirm the server is up
ping-balloon notify complete           # bubble appears, plays sound, auto-hides
ping-balloon notify permission         # bubble appears, plays sound, stays visible

4. Use with Claude Code

Terminal 1 — start Ping Balloon (keep running):

ping-balloon start

Terminal 2 — inside your project:

cd path/to/your/project
ping-balloon hooks install
claude

hooks install needs to be run once per project. It writes to .claude/settings.local.json. If Ping Balloon is not running when Claude triggers a hook, the hook exits silently — it will never interrupt or block Claude Code.

5. Remove hooks

ping-balloon hooks uninstall

Removes only Ping Balloon entries from .claude/settings.local.json. Other hooks are untouched.

6. Update Ping Balloon

npm install -g @quantthieres/ping-balloon@latest

7. Optional — run without installing

npx --package=@quantthieres/ping-balloon ping-balloon help
npx --package=@quantthieres/ping-balloon ping-balloon start

For everyday use the global install (npm install -g) is simpler.

Requirements

Node.js >= 18
macOS (10.15+), Windows (10+), or Ubuntu (22.04 / 24.04 with GNOME)
Claude Code for hook integration (optional but recommended)

CLI Commands

ping-balloon <command> [args]

Command	Description
`start`	Start using the production build in `dist/`
`dev`	Start in dev mode — Vite dev server + Electron (source clone only)
`health`	Check if the HTTP server is reachable
`notify <state>`	Send a state change to the bubble
`hooks install`	Wire Claude Code hooks in `.claude/settings.local.json`
`hooks uninstall`	Remove Ping Balloon hooks
`doctor`	Print a diagnostics report
`help`	Show usage and examples

`notify` flags

ping-balloon notify complete
ping-balloon notify permission --title "Approval needed" --message "Allow bash?" --meta "Bash"
ping-balloon notify waiting     # debug/optional — hidden by default from hooks

HTTP API

When Ping Balloon is running it exposes a local server on http://127.0.0.1:47321.

GET /health

curl http://127.0.0.1:47321/health
# → {"ok":true,"app":"agent-ping"}

Note: "app":"agent-ping" is an internal server identifier kept for compatibility.

POST /notify

curl -X POST http://127.0.0.1:47321/notify \
  -H 'Content-Type: application/json' \
  -d '{"state":"complete"}'

Field	Type	Required
`state`	`"complete"` \| `"waiting"` \| `"permission"`	✓
`title`	string	—
`message`	string	—
`meta`	string	—

Claude Code Integration

Ping Balloon hooks into Claude Code to update the bubble automatically as Claude works.

Install hooks

# Terminal 1 — Ping Balloon must be running
ping-balloon start

# Terminal 2 — inside your project
ping-balloon hooks install

This writes to .claude/settings.local.json (project-scoped, typically git-ignored). Existing hooks from other tools are preserved.

Event routing

Claude Code event	Condition	Bubble behaviour
`Stop` (task done)	always	complete — plays sound, auto-hides after 6 s
`Notification`	message contains a permission keyword	permission — plays sound, stays until dismissed
`Notification`	generic / idle	ignored by default — set `PING_BALLOON_SHOW_WAITING=1` to re-enable

Permission keywords (case-insensitive): permission, allow, approve, authorize, grant, blocked, requires approval, do you want to, confirm

Generic idle notifications are suppressed so the bubble does not flash every time Claude is just thinking. Only task completion and permission requests produce a visible notification.

Debug mode

AGENT_PING_HOOK_DEBUG=1 node scripts/claude-hook-notify.js Stop
cat .claude/agent-ping-hook-debug.log

Each hook invocation appends a JSON line with timestamp, event, payload, chosen state (or skip), and HTTP result.

Remove hooks

ping-balloon hooks uninstall

Only Ping Balloon entries are removed. Other hooks in the same file are preserved.

Environment Variables

Set these before starting Ping Balloon or before running a hook.

Variable	Default	Effect
`PING_BALLOON_SOUND=0`	sound on	Silence all notification sounds
`PING_BALLOON_SHOW_WAITING=1`	suppressed	Show the waiting bubble for generic Claude Code notifications
`AGENT_PING_HOOK_DEBUG=1`	off	Append debug JSON to `.claude/agent-ping-hook-debug.log`
`PING_BALLOON_FOCUS_CMD`	—	Custom shell command used instead of built-in focus logic on Ubuntu/Linux

Disabling sounds

PING_BALLOON_SOUND=0 ping-balloon start

Re-enabling waiting/idle notifications

By default, generic Notification events from Claude Code (idle, thinking) are silently ignored. To restore the previous behaviour:

PING_BALLOON_SHOW_WAITING=1 ping-balloon start

PING_BALLOON_SHOW_WAITING is read by claude-hook-notify.js at hook invocation time. Set it as a shell environment variable or in your shell profile.

Terminal Focus on Click

Clicking the notification bubble tries to bring your terminal or editor to the front.

If focus succeeds, the bubble hides automatically.
If focus fails (no supported app found, permission not granted), the bubble stays visible — dismiss it manually with ×.

macOS

Apps tried in order:

Priority	App
1	Warp
2	iTerm2
3	Terminal
4	Visual Studio Code

Uses AppleScript tell application X to activate. On first use macOS may show an Automation permission dialog — approve it for focus to work.

Windows

Apps tried in order:

Priority	App
1	Windows Terminal
2	PowerShell (`pwsh`, `powershell`)
3	cmd
4	Visual Studio Code

Uses PowerShell AppActivate by PID. The Windows foreground lock may cause the app to flash in the taskbar rather than fully focus.

Ubuntu

Ubuntu 22.04 and 24.04 with GNOME are the initial targets. Other distributions may work but are not tested.

Install

npm install -g @quantthieres/ping-balloon@latest

Usage

ping-balloon start
ping-balloon notify complete
ping-balloon notify permission

Optional dependencies for terminal focus

Without these tools the bubble will still appear and can be dismissed manually, but clicking it will not focus your terminal.

sudo apt update
sudo apt install -y wmctrl xdotool

Focus is attempted in this order:

PING_BALLOON_FOCUS_CMD (if set) — run as a custom shell command
wmctrl -a <name> — tries GNOME Terminal, Terminal, Visual Studio Code, Code
xdotool search --class <class> + windowactivate — tries gnome-terminal, org.gnome.Terminal, code, Code
Returns ok: false with guidance if nothing works

Custom focus command

Use PING_BALLOON_FOCUS_CMD to override the built-in logic with any shell command you prefer:

PING_BALLOON_FOCUS_CMD='wmctrl -a Terminal' ping-balloon start

Wayland

Wayland restricts which applications can raise windows belonging to other processes. If focus does not work on Wayland, install wmctrl or xdotool, or set PING_BALLOON_FOCUS_CMD. Notifications will still appear and sounds will still play regardless of whether focus succeeds.

`ping-balloon doctor` on Ubuntu

doctor shows Ubuntu-specific checks:

✓  Platform: linux x64  6.8.0-57-generic
✓  XDG_SESSION_TYPE: x11
✓  wmctrl: available
✗  xdotool: missing  optional — sudo apt install -y xdotool
✓  PING_BALLOON_FOCUS_CMD: not set (optional)

Optional checks (wmctrl, xdotool, PING_BALLOON_FOCUS_CMD) are shown but do not cause doctor to exit with an error.

npm Scripts

Command	Description
`npm run dev`	Start Vite + Electron in development mode
`npm run build`	Build the React app into `dist/`
`npm start`	Start Electron loading `dist/` (production)
`npm run doctor`	Run `ping-balloon doctor`
`npm run health`	Check if the server is up
`npm run notify:complete`	Send `complete` state
`npm run notify:waiting`	Send `waiting` state (debug)
`npm run notify:permission`	Send `permission` state
`npm run hooks:install`	Install Claude Code hooks
`npm run hooks:uninstall`	Remove Claude Code hooks

Manual Test Checklist

Use this checklist before tagging a release.

App startup

npm run build completes without errors
ping-balloon start starts the process — no bubble visible on launch
ping-balloon health returns {"ok":true,"app":"agent-ping"}
ping-balloon doctor reports all ✓

Bubble states and timing

ping-balloon notify complete → green bubble, DONE label, sound plays, auto-hides after ~6 s
ping-balloon notify permission → amber bubble, HOLD label, sound plays, stays visible
ping-balloon notify waiting → blue bubble, IDLE label, sound plays, auto-hides after ~8 s
Dismiss (×) hides the bubble immediately (cancels any auto-hide timer)
Any notify call re-shows the bubble regardless of current visibility

Sound

Sound plays on complete, permission, waiting events
Theme toggle (☾/☀) produces no sound
PING_BALLOON_SOUND=0 ping-balloon start → bubble appears but no sound

Theme

☾/☀ button toggles light/dark theme
Clicking the theme button does not dismiss the bubble or focus the terminal

Bubble click — terminal focus (macOS)

Single click on the bubble body attempts terminal focus
If focus succeeds → terminal comes to front, bubble hides
If focus fails → bubble stays visible
Double-click does not trigger two focus calls (guard active)

Claude Code hook routing

echo '{"hook_event_name":"Stop"}' | node scripts/claude-hook-notify.js Stop → complete bubble appears
echo '{"hook_event_name":"Notification","message":"Permission required"}' | node scripts/claude-hook-notify.js Notification → permission bubble
echo '{"hook_event_name":"Notification","message":"Waiting for input"}' | node scripts/claude-hook-notify.js Notification → no bubble (suppressed)
PING_BALLOON_SHOW_WAITING=1 echo '...' | node scripts/claude-hook-notify.js Notification → waiting bubble
ping-balloon hooks install writes to .claude/settings.local.json
Claude Code Stop hook → complete bubble
ping-balloon hooks uninstall removes entries cleanly

Bubble click — terminal focus (Ubuntu, manual — requires Ubuntu machine)

wmctrl and/or xdotool installed
Single click on the bubble body attempts terminal focus
If wmctrl or xdotool finds a window → terminal comes to front, bubble hides
If neither tool is available → bubble stays visible, error logged
PING_BALLOON_FOCUS_CMD='wmctrl -a Terminal' ping-balloon start → custom command used on click
ping-balloon doctor on Ubuntu shows XDG_SESSION_TYPE, wmctrl, xdotool, PING_BALLOON_FOCUS_CMD
On Wayland (XDG_SESSION_TYPE=wayland), doctor shows Wayland note

CLI edge cases

ping-balloon notify invalid → error, exit 1
ping-balloon foobar → "Unknown command", exit 1
ping-balloon health when not running → clear error, exit 1
ping-balloon start when dist/ is missing → clear error, exit 1

Package

npm pack --dry-run lists only expected files (no src/, node_modules/, .claude/)
Version shown is 0.3.0

Known Limitations

ping-balloon dev is only available when running from a source clone (requires src/ and Vite). Shows a clear error from an installed package.
Hook routing (permission vs ignored) depends on Claude Code's Notification payload text. If Claude Code changes its message format, keywords in scripts/claude-hook-notify.js may need updating.
Stop hook cannot distinguish a completed task from a cancelled one — always shows complete.
Rapid notifications overwrite each other; the bubble shows the last state received.
macOS Automation permission must be granted to Ping Balloon on first use for terminal focus to work. macOS will show a permission dialog automatically.
Windows terminal focus is best-effort — the foreground lock may cause the app to flash in the taskbar rather than fully focus.
Notification sound depends on OS audio output being available and not muted at the system level.
Ubuntu terminal focus is best-effort — requires wmctrl or xdotool, or a custom PING_BALLOON_FOCUS_CMD. Wayland may restrict focus further. See Ubuntu.
Other Linux distributions are not tested. The Electron window may open but terminal focus is not implemented beyond Ubuntu.
Fixed port — the server runs on 47321. If that port is in use, the server will fail silently.
Internal identifiers ("app":"agent-ping" in the HTTP response, agent-ping-hook-debug.log, AGENT_PING_HOOK_DEBUG) are legacy names kept for backward compatibility.

VS Code Integration

The vscode-extension/ folder contains a companion VS Code extension (local/dev only — not published to the Marketplace).

What it does

Shows a status bar item (bottom-right) reflecting Ping Balloon's running/offline state, refreshed every 30 s
Exposes six Command Palette commands: Start, Check Status, Install Claude Code Hooks, Test Complete, Test Permission, Doctor
Clicking the status bar opens a quick-pick menu with all commands
All invocations pass PING_BALLOON_FOCUS_TARGET=vscode so the bubble click focuses VS Code first

VS Code focus target

When PING_BALLOON_FOCUS_TARGET=vscode is set, clicking the bubble promotes VS Code to the top of the focus order on macOS, Windows, and Ubuntu/Linux.

You can also set this from the CLI without the extension:

ping-balloon start --focus vscode
# or
PING_BALLOON_FOCUS_TARGET=vscode ping-balloon start

Using the extension locally

cd vscode-extension
npm install
npm run compile
# Then open the folder in VS Code and press F5 to launch an Extension Development Host.

Development

git clone https://github.com/quantthieres/ping-claude-balloon.git
cd ping-claude-balloon/agent-ping-desktop

npm install       # install all dependencies
npm run dev       # Vite hot-reload + Electron

Project structure

agent-ping-desktop/
├── bin/
│   └── agent-ping.js            ← CLI entry point (ping-balloon command)
├── electron/
│   ├── main.js                  ← Electron main process + HTTP server
│   ├── preload.js               ← IPC bridge (contextBridge)
│   └── focus-terminal.js        ← macOS / Windows / Ubuntu terminal focus
├── scripts/
│   ├── claude-hook-notify.js    ← Hook entry point (reads stdin, routes state)
│   ├── electron-dev.js          ← Cross-platform Electron dev launcher
│   ├── notify.js                ← HTTP helper for npm scripts
│   ├── install-claude-hooks.js
│   └── uninstall-claude-hooks.js
├── src/
│   ├── App.jsx                  ← State switcher, IPC listener, sound, timers
│   ├── main.jsx
│   └── components/
│       ├── BubbleNotification.jsx
│       ├── BubbleNotification.css
│       ├── state-config.js
│       └── mascots/             ← complete.png, waiting.png, permission.png
├── dist/                        ← Production build (generated by npm run build)
├── package.json
├── README.md
├── CHANGELOG.md
└── LICENSE

Building

npm run build           # build React app into dist/
npm pack                # creates .tgz (runs build first via prepack)
npm pack --dry-run      # preview contents without writing the file

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
bin		bin
electron		electron
scripts		scripts
src		src
vscode-extension		vscode-extension
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation