cc-notify

cc-notify

Local notification filter for AI coding tools. Debounces notifications so you only get pinged when a tool is genuinely waiting for you — not when you're actively working.

How it works

1. An AI tool (e.g. Claude Code) sends a notification request with a session ID
2. A 60-second timer starts
3. If activity is detected on that session within 60s, the notification is cancelled
4. If the terminal pane is focused (or regains focus), the notification is suppressed
5. If the timer expires with no activity or focus, a push notification is sent via Pushover

Focus tracking currently supports tmux, with the design open to other terminals. See specs/claude-code-plugin.md for details.

Claude Code Plugin

This repo doubles as a Claude Code plugin. Once enabled, it automatically hooks into Stop, PermissionRequest, UserPromptSubmit, and SessionEnd events — no manual hook configuration needed.

Add to your settings.json:

{
  "extraKnownMarketplaces": {
    "cc-notify-marketplace": {
      "source": { "source": "github", "repo": "codethread/cc-notify" }
    }
  },
  "enabledPlugins": {
    "cc-notify@cc-notify-marketplace": true
  }
}

For tmux focus tracking, add this to your tmux.conf:

set-hook -g pane-focus-in 'run-shell "~/.claude/plugins/data/cc-notify-cc-notify-marketplace/tmux-focus.js"'

See specs/claude-code-plugin.md for how this works.

Server Setup

Requires Bun and a Pushover account.

Set your Pushover credentials via environment variables or a .env file:

PUSHOVER_CC_KEY=<your pushover application token>
PUSHOVER_DEV_KEY=<your pushover user key>

Start the server:

bun run src/main.ts

The server picks an available port starting at 7777 and writes it to $XDG_RUNTIME_DIR/cc-notify.port for service discovery.

API

All endpoints use http://localhost:<port>.

Endpoint	Method	Description
/notify	POST	Schedule a notification (title, session_id, message, optional notify_at epoch milliseconds)
/activity	POST	Cancel a pending notification (session_id)
/toggle	GET	Toggle notifications on/off
/health	GET	Health check

Example

PORT=$(cat "$XDG_RUNTIME_DIR/cc-notify.port")

# schedule a notification
curl -X POST "http://localhost:$PORT/notify" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Task done", "session_id": "abc", "message": "Build complete"}'

# schedule for a specific time from the CLI
echo "Build complete" | cc-notify --after 4h "Task done"
echo "Build complete" | cc-notify --at "2026-06-14 17:30" "Task done"

# cancel it (user is active)
curl -X POST "http://localhost:$PORT/activity" \
  -H 'Content-Type: application/json' \
  -d '{"session_id": "abc"}'