ZekerTop/ai-cli-complete-notify

AI CLI Complete Notify – What It Does

Purpose – The program watches the output of AI‑assistant command‑line tools (Claude Code, Codex, OpenCode, Gemini CLI, ZCode, etc.) and sends you a notification when a long‑running task finishes. It lets you keep working elsewhere while the AI runs, then alerts you via the channel(s) you prefer.

How It Works

• Monitoring – The app can either watch the log files those CLIs write (polling for a quiet period) or install hooks/plugins that the AI CLI itself emits when a turn ends. Hooks give faster, more reliable signals; watching is a universal fallback.
• Debounce / Threshold – After a task ends the tool waits a short “quiet” period (default 60 s when the AI used tools, 15 s otherwise) before sending a notification. You can also set a duration threshold so you only get alerts for tasks that ran longer than a given time.
• Multi‑channel Delivery – One notification can be pushed through any combination of:
  • Desktop toast (Windows, macOS, Linux)
  • Sound or text‑to‑speech
  • Smart‑watch/band (via the same channels)
  • Webhook to Feishu, DingTalk, WeCom, etc.
  • Telegram bot
  • Email (SMTP)
• Optional AI Summary – If you enable it, the tool calls an LLM (configurable URL/key/model) to generate a short summary of the completed task. If the summary request times out, the original task description is used instead.

Main Features (as listed in the README)

Feature	What It Means
Smart Debouncing	Auto‑adjusts wait time before notifying (60 s with tool calls, 15 s without).
Source Control	Turn each AI source on/off and set its own duration threshold.
Multi‑Channel Push	Send the same alert via several methods at once.
Duration Threshold	Skip notifications for short tasks to avoid spam.
Hooks + Watch Integration	Prefer native hooks for Claude, Gemini, ZCode, OpenCode; fall back to log‑watch for Codex.
AI Summary (Optional)	Generates a brief natural‑language recap of the completed turn.
Desktop Application	GUI (Tauri‑based) with language switching, tray icon, auto‑start, hide‑from‑Dock, etc.
Configuration Separation	Sensitive data (API keys, SMTP passwords) live in a separate .env file, keeping them out of the UI‑generated settings.json.

Getting Started

1. Download – Pre‑built binaries are provided for Windows (portable zip), macOS (DMG/app), and source for Linux/WSL.
2. Configure – Copy .env.example to .env and fill in webhook URLs, Telegram bot token, SMTP credentials, and (optionally) LLM API details.
3. Run –
   • GUI – Double‑click the app (or run ai-cli-complete-notify.exe on Windows). The first launch creates a default .env.example if none exists.
   • CLI – Use the bundled ai-reminder (or ai-reminder.exe) for command‑line control, e.g. ai-reminder watch --sources all to start background monitoring, or ai-reminder run --source codex -- codex <args…> to wrap a single command.
4. Install Hooks (recommended) – Run ai-reminder hooks install --target claude (or gemini, opencode, zcode, herdr) to drop the appropriate hook/plugin into the AI CLI’s config directory. This gives near‑instant notifications.
5. Test – Use the “Test Function” in the GUI or ai-reminder notify --source claude --task "Demo" to verify each channel works.

Typical Workflows

• Background Watch – Start ai-reminder watch … in a tmux or screen session. The tool silently watches logs; when a Claude or Gemini turn finishes and exceeds your threshold, you get a desktop toast, a sound, and/or a Telegram message.
• One‑off Command – Prefix any AI CLI call with ai-reminder run --source codex -- so the timer starts automatically and a notification is sent when the command exits.
• Manual Timing – Use ai-reminder start … before you begin a long task, then ai-reminder stop … after it finishes (useful for non‑CLI tools).

Platform Details

• macOS – Distributed as a signed DMG containing a bundled Node.js runtime; no separate Node/Rust installation needed. Supports Apple Silicon and Intel builds.
• Windows – Portable zip includes both the GUI (ai-cli-complete-notify.exe) and the CLI sidecar (ai-reminder.exe). Desktop notifications and sounds are handled via PowerShell when run from WSL.
• Linux / WSL – Run from source (npm install && node ai-reminder.js …). Requires Node ≥ 14 and Rust/Cargo for the Tauri build.

Extensibility

• Third‑party Herdr integration – The tool can install the herdr-ai-notify plugin, allowing Herdr‑managed AI sessions to trigger notifications.
• Custom webhook URLs – Add any HTTP endpoint that accepts a JSON payload; the UI lets you name the channel and test it.

Who Might Use It?

• Developers who run Claude, Gemini, Codex, etc. for code generation, data‑analysis, or long‑running prompts and want to be alerted when the model finishes.
• Researchers experimenting with LLM‑driven pipelines that can take minutes or hours.
• Anyone who prefers to keep the terminal window hidden while the AI works and still stay informed.

---

TL;DR – AI CLI Complete Notify is a cross‑platform helper that watches AI‑assistant CLIs, optionally installs native hooks, and pushes completion alerts through desktop, sound, email, Telegram, or custom webhooks. It’s useful for anyone who runs long AI‑driven commands and wants a reliable “task finished” ping.