ai-cli-complete-notify

Sponsors

Want to sponsor this project?

  gptplus.uno

gptplus.uno offers ChatGPT Plus / Pro purchase and upgrade guides, plan-selection advice, FAQs and self-service troubleshooting, with WeChat Pay and Alipay payment options. Thank you for supporting this open-source project.

Introduction

An intelligent task completion notification tool for Claude Code / Codex / OpenCode / Gemini / ZCode, supporting multiple notification channels and flexible configuration options. Get notified automatically through various methods when AI assistants complete long-running tasks, so you don't have to wait in front of your computer.

Supported Notification Methods:

Webhook (Feishu/DingTalk/WeCom) • Telegram Bot • Email (SMTP)

️ Desktop Notifications • Sound/TTS Alerts • ⌚ Smart Band / Watch Alerts (via existing notification channels)

✨ Key Features(For more detailed update logs, please refer to the end of the article)

• Smart Debouncing: Automatically adjusts notification timing based on task type - 60s for tool calls, only 15s without tool calls
• Source Control: Independent enable/disable and threshold settings for Claude / Codex / OpenCode / Gemini / ZCode
• Multi-Channel Push: Support multiple notification methods simultaneously to ensure message delivery
• ⏱️ Duration Threshold: Only notify when tasks exceed the set duration to avoid frequent interruptions
• Hooks + Watch Integration: Claude Code / Gemini CLI / ZCode can use native hooks, OpenCode can use a global plugin, while Codex continues through log watching
• AI Summary (Optional): Generate a short summary quickly; fallback to the original task if it times out
• ️ Desktop Application: GUI configuration with language switching, tray hiding, and auto-start
• Configuration Separation: Runtime configuration separated from sensitive information for security

Recommended Configuration

Important: For the best experience, it's recommended to grant AI assistants full file read/write permissions when using Claude Code / Codex / OpenCode / Gemini. ZCode is not affected: it completes through its native Stop hook and has no Watch path, so it does not need these permissions.

Benefits:

• ✅ Ensures task logs are correctly recorded to local files
• ✅ Monitoring functions can accurately capture task completion status
• ✅ More precise notification timing, avoiding false positives or missed notifications
• ✅ AI can better manage project files and configurations

Important Notes

• Claude Code often splits a request into sub-tasks. To avoid spam, this tool only notifies after the whole turn completes.
• Log monitoring relies on a quiet period to confirm completion, so notifications are not instant (default 60s with tool calls, 15s without).
• For the fastest and cleanest alerts, prefer Hooks for Claude Code / Gemini CLI / ZCode and the global plugin for OpenCode; keep Watch for Codex or as a general fallback mode.
• Watch and Hooks can run together in hybrid mode. Recommended hybrid setup: Codex uses Watch; Claude Code / Gemini / OpenCode / ZCode use Hooks or plugins. If both paths fire for the same source, content-based dedupe keeps only one alert. Watch-only mode suppresses Claude/Gemini installed hooks so the two options stay distinct; hook-only sources (OpenCode, Herdr, ZCode) are never silenced by it.

Hooks vs Watch

• Hooks / plugin events use explicit lifecycle events emitted by the AI CLI itself. For Claude Code, Gemini CLI, OpenCode, and ZCode, that means reminders can fire closer to the real finish point instead of waiting for a quiet-period guess.
• Hooks do not require a long-running background watcher for those tools, which reduces idle overhead and lowers the chance of log-parsing false positives.
• Watch remains the universal fallback. It works well for Codex and for cases where hooks are not configured, but it depends on local logs and debounce time to infer that a turn has ended.
• In practice, Hooks / plugin events were added because Claude Code's Stop, ZCode's Stop, Gemini CLI's AfterAgent, and OpenCode's session.status idle / session.idle / session.error events provide more timely and accurate completion signals than watch-based log polling. In the current integration, Codex still uses Watch as the main completion path.

Quick Start

Windows Users

1. Download the latest ai-cli-complete-notify--portable-win-x64.zip from Releases
2. Extract the archive and place it in any directory (e.g., D:\Tools\)
3. Copy .env.example to .env and fill in your notification configuration according to the requirements inside
4. Double-click to run the desktop application

macOS / Linux Users

macOS: Install the DMG (Recommended)

1. Download the DMG matching your Mac from GitHub Releases:
   • Apple Silicon (M-series): ai-cli-complete-notify__aarch64.dmg
   • Intel: ai-cli-complete-notify__x86_64.dmg
2. Open the DMG and drag ai-cli-complete-notify.app into Applications.
3. On first launch, if macOS says the developer cannot be verified, right-click the app and choose Open.
4. The packaged app reads notification settings from ~/.ai-cli-complete-notify/.env. On first launch it creates .env.example there when configuration is missing.

Requires macOS 13.5 or later (the bundled Node.js runtime's minimum). Check About This Mac to identify your chip or processor. These are separate architecture-specific packages, not Universal binaries. Both include Node.js; installing the DMG does not require Node.js/npm or Rust/Cargo.

Run from Source (macOS / Linux)

The following steps are only needed for Linux, development, or users who prefer to build from source. Source/dev mode requires Node.js/npm and Rust/Cargo. Tauri calls cargo when running npm run dev; if cargo --version fails, install Rust from the official Rust installation page first.

# Clone repository
git clone https://github.com/ZekerTop/ai-cli-complete-notify.git
cd ai-cli-complete-notify

# Verify Rust/Cargo is available
cargo --version

# Install dependencies
npm install

# Configure environment variables (source/dev mode)
cp .env.example .env
# Edit .env file and fill in your notification configuration

# Run desktop application
npm run dev

Optional: build a double-clickable macOS app from source:

# Build .app
npm run dist:mac:app

# Build .dmg for distribution
npm run dist:mac:dmg

️ Desktop Application Usage

Interface Overview

• Top Bar: Language switching, Watch monitoring toggle, window controls
• Channel Configuration: Configure Webhook, Telegram, Email, and other notification channels
• Source Settings: Set enable status and duration thresholds for Claude / Codex / OpenCode / Gemini / ZCode separately
• Monitoring Configuration: Set polling interval and debounce time with smart adjustment support
• Confirm reminder (default: OFF): Effective only in Watch mode. When enabled, it triggers only when Codex shows an interactive choice prompt that requires your selection or submission (Plan mode); normal output text will not trigger it. Only one reminder is sent per turn: once a confirm reminder is triggered, that turn will not send a separate task-complete reminder.
• Watch logs: Persisted locally with one-click open and retention days.
• Test Function: Test whether each notification channel works properly
• AI Summary: Configure API URL / Key / Model and timeout fallback
• Advanced Options: Title prefix, close behavior, auto-start on boot, silent start (hide to tray on launch), hide the Dock icon (macOS only), click notification to return (best-effort; OS focus rules may block)

Interface Preview

Tray Function

After selecting "Hide to tray", the application hides its window and keeps running. On Windows, the icon may be in the taskbar's ^ collapsed area; on macOS, use the menu bar icon to reopen the window. With silent start enabled, the app launches hidden in the tray without a balloon.

On macOS, enable Advanced → Hide from Dock (show only in macOS menu bar) to hide the Dock icon. This setting is off by default and is saved as ui.hideDockIcon; it is separate from silent start and close behavior. Click the menu bar icon, or choose Show from its menu, to reopen the window. If you use Ice or another menu bar manager and cannot find the icon, check its hidden sections and available menu bar space, then refresh the manager's layout.

Command Line Usage

WSL note: CLI reminders work for webhook/Telegram/email, and sound can also work in WSL through Windows PowerShell. Desktop notifications and tray are Windows-only. Log monitoring works only when the AI CLI runs inside WSL (logs under ~/.claude, ~/.codex, ~/.gemini). For WSL/CLI config, use .env for AI summary and Feishu card; .env overrides settings.json.

Note: For CLI usage from source (Node), run npm install first.

On Windows portable builds:

• ai-cli-complete-notify.exe is the desktop GUI.
• ai-reminder.exe is the packaged CLI/sidecar and should be used for terminal commands.

Show Help

# Source / Node
node ai-reminder.js help

# Windows portable EXE
ai-reminder.exe help

WSL Quick Command Guide (Copy & Run)

# 0) Windows PowerShell: verify WSL is installed
wsl -l -v

# 1) Enter your distro (Ubuntu example)
wsl -d Ubuntu

# 2) Install Node.js / npm inside WSL (Ubuntu example)
sudo apt update
sudo apt install -y nodejs npm
node -v
npm -v

# 3) Enter project and install deps (adjust path to your machine)
cd "/mnt/d/path/to/ai-cli-complete-notify"
npm install
cp .env.example .env

# 4) Start log watch mode (recommended for long-running use)
node ai-reminder.js watch --sources all --gemini-quiet-ms 3000 --claude-quiet-ms 60000

# 5) Wrap an AI command with automatic timing
node ai-reminder.js run --source codex -- codex 

# 6) Keep watcher running in background (nohup option)
nohup node ai-reminder.js watch --sources all > ~/ai-cli-notify.watch.log 2>&1 &
tail -f ~/ai-cli-notify.watch.log

# 7) Optional: keep it in tmux (more stable)
sudo apt install -y tmux
tmux new -s ai-notify
# Run watch command inside tmux, then press Ctrl+b, d to detach
tmux attach -t ai-notify

# 8) Useful WSL  Windows path helpers
explorer.exe .
wslpath -w ~/.codex

Notes:

• In WSL, prefer webhook/Telegram/email channels; tray is a Windows GUI feature.
• For WSL CLI behavior, prefer .env for webhook and summary-related settings; global channel switches already saved in the desktop app still follow settings.json.

Direct Notification

# Send notification immediately (ignore threshold)
node ai-reminder.js notify --source claude --task "Task completed"

Native Hooks / Plugin Mode (Recommended for Claude Code / Gemini CLI / OpenCode / ZCode)

…

Notes:

• Claude Code currently uses the native Stop hook event.
• Gemini CLI currently uses the native AfterAgent hook event.
• OpenCode currently uses a global plugin and listens to session.status idle / session.idle / session.error.
• ZCode uses hooks only, has no Watch path, and is disabled by default (sources.zcode.enabled). Installation registers UserPromptSubmit and Stop process hooks in the user-level ~/.zcode/cli/config.json and enables hooks.enabled. Existing settings and other hooks are preserved; uninstall removes only this tool’s handlers.
• Enable the ZCode source, install its hook under Hooks / Plugin Integration, then start a new ZCode session. UserPromptSubmit starts the timer and Stop checks the