Skip to content

README.md

Latest commit

 

History

History
170 lines (134 loc) · 6.47 KB

README.md

File metadata and controls

170 lines (134 loc) · 6.47 KB
Raw

ai-notify

ai-notify

Play a sound when an AI coding agent finishes or needs your attention, but only when its terminal window is not focused.
No noise while you are watching it work, a bell when you have switched away.

Here is a Medium article about this project.

Platforms: Linux (Ubuntu), macOS, and Windows

Agents: Claude Code, Codex, and opencode

Usage

Install in one command:

# Linux or Mac
git clone https://github.com/Helias/ai-notify.git && cd ai-notify && ./install.sh

# Windows
git clone https://github.com/Helias/ai-notify.git; cd ai-notify; powershell -ExecutionPolicy Bypass -File .\install.ps1

...or you can ask your agent to install it for you 😉

How it works

On Linux and macOS, notify-if-unfocused.sh detects the OS and the currently focused window, walks up its own process tree, and plays a sound only when none of its ancestor processes own the focused window. On Windows, notify-if-unfocused.ps1 does the same with the Win32 API.

  • Linux: focused window via xdotool; sound via the first available player, trying paplay, pw-play, ffplay, then aplay.
  • macOS: frontmost app via osascript, sound via afplay.
  • Windows: foreground window via GetForegroundWindow/GetWindowThreadProcessId (PowerShell + Win32); sound via a built-in notification .wav (System.Media.SoundPlayer), falling back to a system sound. conhost.exe/OpenConsole.exe windows are resolved to their owning shell so classic consoles and Windows Terminal both work.

Requirements

install.sh checks for these and offers to install any that are missing using your package manager. You can also install them yourself:

  • Linux: xdotool (sudo apt install xdotool). Works on X11; Wayland support depends on xdotool compatibility. For sound you almost certainly already have a player (paplay or pw-play ship with the PulseAudio/PipeWire desktop stack); only if you have none of paplay, pw-play, ffplay, or aplay do you need to install one, e.g. sudo apt install ffmpeg.
  • macOS: no extra tooling, osascript and afplay ship with the system.
  • Windows: no extra tooling. notify-if-unfocused.ps1 and install.ps1 use only built-in PowerShell (5.1+, ships with Windows) and the Win32 API — no jq, xdotool, or sound player to install. If your environment restricts scripts, the installer/hook commands already pass -ExecutionPolicy Bypass.
  • jq is required by install.sh (Linux/macOS only). Install it with sudo apt install jq or brew install jq. The Windows installer (install.ps1) does its JSON merging natively and needs no jq.

Configurations

 Claude Code

Merge the hooks (and preferredNotifChannel) from templates/claude/settings.json into your ~/.claude/settings.json. It fires the script on Stop and on permission/idle notifications.

{
  "preferredNotifChannel": "notifications_disabled",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash [COMMAND_PATH]/notify-if-unfocused.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "bash [COMMAND_PATH]/notify-if-unfocused.sh"
          }
        ]
      }
    ]
  }
}

On Windows, use templates/claude/settings.windows.json instead (same structure, with the command set to powershell -NoProfile -ExecutionPolicy Bypass -File "[COMMAND_PATH]/notify-if-unfocused.ps1"). .\install.ps1 claude does this merge for you.

 Codex

Copy templates/codex/hooks.json to ~/.codex/hooks.json (or merge its hooks into your existing one). It fires the script on Stop.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "[COMMAND_PATH]/notify-if-unfocused.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

On Windows, use templates/codex/hooks.windows.json instead (command set to powershell -NoProfile -ExecutionPolicy Bypass -File "[COMMAND_PATH]/notify-if-unfocused.ps1"). .\install.ps1 codex does this for you.

 opencode

Two files under ~/.config/opencode/:

  1. templates/opencode/opencode.jsonc enables the built-in attention notification:

    {
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "attention": {
      "notify": true,
      "sound": true,
    },
  },
}

  2. templates/opencode/plugin/notify.js runs the script on session.idle. Remember to replace [COMMAND_PATH] inside it.

    On Windows, use templates/opencode/plugin/notify.windows.js instead — it invokes notify-if-unfocused.ps1 via powershell. .\install.ps1 opencode installs it for you. (opencode.jsonc is identical on every platform.)