ai-ding

English | 中文

🔔 ai-ding

Never stare at a terminal waiting for AI to finish again.

Cross-platform notifications for Claude Code and Codex CLI.
Desktop popups, sound alerts, Telegram, Bark, Slack, email — pick your channels.
Works over SSH. Zero config for basic usage.

---

Why ai-ding?

You run claude and wait... and wait... 10 minutes later you realize it finished 5 minutes ago. Or worse — it's asking you a question and you didn't notice.

ai-ding alerts you the instant your AI assistant needs your attention:

• When it finishes responding — with a summary of what it said
• When it asks you a question — so you can answer immediately
• When it needs permission — no more missed approval dialogs
• When it's waiting for your input — never miss a prompt again

Supported Channels

Channel	macOS	Linux	SSH	Config Required
Desktop	✅	✅	❌	None
Sound	✅	✅	✅	None
Telegram	✅	✅	✅	Bot token
Slack	✅	✅	✅	Webhook URL
Bark (iOS)	✅	✅	✅	Device key
Server酱 (WeChat)	✅	✅	✅	SendKey
ntfy.sh	✅	✅	✅	Topic URL
Email	✅	✅	✅	SMTP credentials

Sound + desktop work out of the box. Enable more channels in ~/.ai-ding.yaml.

Quick Start

As a Claude Code plugin (recommended)

/plugin marketplace add qinsz01/ai-ding
/plugin install ai-ding@qinsz01

That's it. You'll get notifications automatically when Claude finishes, asks a question, or needs permission.

As a CLI tool

npm install -g ai-ding
ai-ding --init    # Create ~/.ai-ding.yaml
ai-ding --test    # Test all enabled channels

As a Codex plugin

ai-ding now supports Codex in both repo-local and personal-install setups.

Repo-local setup

If you cloned this repository, it already includes the required Codex files:

• .agents/plugins/marketplace.json to expose the plugin in the workspace marketplace
• .codex/hooks.json to send Stop-event notifications from the repo's dist/cli.js

Open the repo in Codex, enable hooks in ~/.codex/config.toml if needed:

[features]
codex_hooks = true

Then restart Codex and install ai-ding from /plugins if you want the notify skill in chat. Repo-level Stop notifications work through .codex/hooks.json.

Personal install

If you installed ai-ding globally with npm, run:

ai-ding --install-codex

This will:

• copy the plugin source to ~/.codex/plugins/ai-ding
• update ~/.agents/plugins/marketplace.json
• write ~/.codex/hooks.json
• enable features.codex_hooks = true in ~/.codex/config.toml

Restart Codex afterward. Automatic Stop notifications will work immediately; install ai-ding from /plugins if you also want the notify skill inside Codex chat.

To remove the personal setup:

ai-ding --uninstall-codex

Usage

# Send a notification (auto-detects environment)
ai-ding "Build complete"

# With a custom title
ai-ding --title "CI Pipeline" "All tests passed"

# Send to a specific channel only
ai-ding --channel telegram "Deploy failed"

# Disable specific channels
ai-ding --no-desktop --no-sound "Silent alert"

# Test all configured channels
ai-ding --test

# Initialize config file
ai-ding --init

# Install personal Codex integration
ai-ding --install-codex

# Remove personal Codex integration
ai-ding --uninstall-codex

Output

Every invocation prints per-channel results so you know exactly what happened:

[ai-ding] ✓ sound: terminal bell
[ai-ding] ✓ telegram: sent to chat 1234...
[ai-ding] ✓ slack: sent to Slack webhook
[ai-ding] Done: 3 sent.

If a channel fails, it shows the error:

[ai-ding] ✓ sound: terminal bell
[ai-ding] ✗ telegram: HTTP 401: Unauthorized
[ai-ding] Done: 1 sent, 1 failed.

Smart Notifications (Plugin Mode)

Claude Code

When installed as a Claude Code plugin, ai-ding sends contextual notifications: