HeyHuman

A notification bell for AI coding tools.

HeyHuman plays a sound, and can optionally show a system notification, when Claude Code, Codex, Gemini CLI, or another AI coding tool calls it from a hook.

Why HeyHuman?

AI coding agents often need your attention when they finish, encounter a system error, or ask for input. HeyHuman gives those moments a clear local signal.

AI coding tool hook
        │
        ▼
   HeyHuman CLI
        │
        ├── plays a configured sound
        └── optionally shows an OS notification

Features

• Cross-platform CLI for macOS and Windows.
• Event presets for complete, attention, and error.
• Built-in generated WAV sounds; no sound assets to download.
• Optional OS notifications.
• Hook-safe behavior for AI coding tool integrations.
• JSON config stored in ~/.config/heyhuman/config.json.

Requirements

• Go 1.22 or newer.
• macOS or Windows for sound playback.

Linux can build the project, but sound and notification playback are not implemented yet.

Quick start from source

Clone, test, and build:

git clone https://github.com/NeoXue-ai/HeyHuman.git
cd HeyHuman
go test ./...
go build -o HeyHuman .

Run the CLI:

./HeyHuman help

On Windows, the build output is usually HeyHuman.exe:

.\HeyHuman.exe help

First-run setup

Run the guided setup, then install Claude Code hooks:

HeyHuman setup
HeyHuman install

If you are running from the project directory on Windows, use:

.\HeyHuman.exe setup
.\HeyHuman.exe install

setup guides through sound choices for complete, attention, and error. Use ↑/↓ to highlight and immediately preview a sound, Enter to select it, s to skip an event, or Esc/Ctrl+C to cancel without saving.

install writes async Claude Code hooks into ~/.claude/settings.json using the current executable path. It preserves user-managed hooks and replaces only HeyHuman-managed hooks.

Verify the configured sounds:

HeyHuman test

On Windows from the project directory:

.\HeyHuman.exe test

To remove the hooks later:

HeyHuman uninstall

Commands

Configure and manage hooks

HeyHuman setup
HeyHuman install
HeyHuman uninstall

Play a known event

HeyHuman play --tool claude --event complete
HeyHuman play --tool codex --event attention
HeyHuman play --tool gemini --event error

Supported events are complete, attention, and error. limit is accepted as a legacy alias for error.

Read a hook payload from stdin

HeyHuman notify --tool claude < payload.json

HeyHuman reads the payload and infers the event.

Show help

HeyHuman help

Claude Code integration

Run this after HeyHuman setup:

HeyHuman install

HeyHuman backs up an existing Claude Code settings file to ~/.claude/settings.json.heyhuman-backup, removes old HeyHuman-managed hook entries, and adds async hooks for configured events:

• Stop -> HeyHuman play --tool claude --event complete
• Notification -> HeyHuman play --tool claude --event attention
• PreCompact with matcher auto -> HeyHuman play --tool claude --event error

Each managed hook entry is marked with _heyhuman: true, so repeated installs are safe and uninstall removes only HeyHuman-managed hooks.

To remove HeyHuman hooks:

HeyHuman uninstall

Configuration

HeyHuman stores config in:

~/.config/heyhuman/config.json

Generated sound files are stored under:

~/.config/heyhuman/sounds/

Run HeyHuman setup again to update the config.

Troubleshooting

Problem	Fix
HeyHuman is not found	Run it with a relative path such as ./HeyHuman or .\HeyHuman.exe, or move the binary to a directory on your PATH.
HeyHuman test reports missing config	Run HeyHuman setup first.
Sound playback fails on Linux	Use macOS or Windows; Linux playback is not implemented yet.