ZekerTop/ai-cli-complete-notify

AI CLI Complete Notify – 기능 소개

목적 – 이 프로그램은 AI 어시스턴트 명령줄 도구(Claude Code, Codex, OpenCode, Gemini CLI, ZCode 등)의 출력을 모니터링하고, 장시간 실행되는 작업이 완료되면 알림을 보냅니다. AI가 실행되는 동안 다른 작업을 계속할 수 있으며, 완료 시 선호하는 채널을 통해 알림을 받을 수 있습니다.

작동 방식

• 모니터링 – 앱은 CLI가 작성하는 로그 파일을 감시(정적 기간 폴링)하거나, AI CLI 자체가 턴 종료 시 출력하는 후크/플러그인을 설치할 수 있습니다. 후크는 더 빠르고 안정적인 신호를 제공하며, 감시는 범용적인 대체 수단입니다.
• 디바운스 / 임계값 – 작업 종료 후 도구는 짧은 "정적" 기간(AI가 도구를 사용한 경우 기본 60초, 그렇지 않으면 15초)을 기다린 후 알림을 보냅니다. 또한 지정 시간 임계값을 설정하여 특정 시간 이상 실행된 작업에 대해서만 알림을 받도록 할 수 있습니다.
• 멀티 채널 전달 – 하나의 알림을 다음 조합으로 푸시할 수 있습니다:
  • 데스크톱 알림(Windows, macOS, Linux)
  • 사운드 또는 텍스트 음성 변환(TTS)
  • 스마트워치/밴드(동일 채널 경유)
  • Feishu, DingTalk, WeCom 등의 Webhook
  • Telegram 봇
  • 이메일(SMTP)
• 선택적 AI 요약 – 활성화 시 도구가 LLM(설정 가능한 URL/키/모델)을 호출하여 완료된 작업의 짧은 요약을 생성합니다. 요약 요청이 시간 초과되면 원래 작업 설명이 대신 사용됩니다.

주요 기능(README에 나열됨)

기능	의미
스마트 디바운스	알림 전 대기 시간 자동 조정(도구 호출 시 60초, 미사용 시 15초).
소스 제어	각 AI 소스의 켜기/끄기 및 개별 지속 시간 임계값 설정.
멀티 채널 푸시	여러 방법으로 동시에 동일한 알림 전송.
지정 시간 임계값	짧은 작업의 알림을 건너뛰어 스팸 방지.
후크 + 감시 통합	Claude, Gemini, ZCode, OpenCode는 네이티브 후크 우선, Codex는 로그 감시로 대체.
AI 요약(선택 사항)	완료된 턴에 대한 간략한 자연어 요약 생성.
데스크톱 애플리케이션	언어 전환, 트레이 아이콘, 자동 시작, Dock 숨기기 등을 지원하는 Tauri 기반 GUI.
설정 분리	민감한 데이터(API 키, SMTP 비밀번호)는 별도의 .env 파일에 저장하여 UI 생성 settings.json에 포함되지 않도록 함.

시작하기

1. 다운로드 – Windows(포터블 zip), macOS(DMG/app)용 사전 빌드된 바이너리와 Linux/WSL용 소스가 제공됩니다.
2. 설정 – .env.example을 .env로 복사하고 Webhook URL, Telegram 봇 토큰, SMTP 자격 증명 및(선택 사항) LLM API 세부 정보를 입력합니다.
3. 실행 –
   • GUI – 앱을 더블 클릭합니다(Windows에서는 ai-cli-complete-notify.exe 실행). 첫 실행 시 .env.example이 없으면 기본값이 생성됩니다.
   • CLI – 번들된 ai-reminder(또는 ai-reminder.exe)를 사용하여 명령줄 제어를 수행합니다. 예: ai-reminder watch --sources all로 백그라운드 모니터링 시작, 또는 ai-reminder run --source codex -- codex <args…>로 단일 명령 래핑.
4. 후크 설치(권장) – ai-reminder hooks install --target claude(또는 gemini, opencode, zcode, herdr)를 실행하여 적절한 후크/플러그인을 AI CLI 설정 디렉토리에 배치합니다. 이를 통해 즉각적인 알림이 가능합니다.
5. 테스트 – GUI의 "테스트 기능" 또는 ai-reminder notify --source claude --task "Demo"를 사용하여 각 채널이 작동하는지 확인합니다.

일반적인 워크플로우

• 백그라운드 모니터링 – tmux 또는 screen 세션에서 ai-reminder watch …를 시작합니다. 도구가 조용히 로그를 감시하다가 Claude나 Gemini 턴이 완료되고 임계값을 초과하면 데스크톱 알림, 사운드, Telegram 메시지를 받습니다.
• 일회성 명령 – AI CLI 호출 앞에 ai-reminder run --source codex --를 붙이면 타이머가 자동으로 시작되고 명령 종료 시 알림이 전송됩니다.
• 수동 타이밍 – 긴 작업 시작 전 ai-reminder start …를 사용하고, 종료 후 ai-reminder stop …을 사용합니다(CLI 이외 도구에 유용).

플랫폼 세부 정보

• macOS – 번들된 Node.js 런타임이 포함된 서명된 DMG로 배포. 별도의 Node/Rust 설치 불필요. Apple Silicon 및 Intel 빌드 지원.
• Windows – 포터블 zip에 GUI(ai-cli-complete-notify.exe)와 CLI 사이드카(ai-reminder.exe) 포함. WSL에서 실행 시 데스크톱 알림과 사운드는 PowerShell을 통해 처리됨.
• Linux / WSL – 소스에서 실행(npm install && node ai-reminder.js …). Node ≥ 14 및 Tauri 빌드용 Rust/Cargo 필요.

확장성

• 타사 Herdr 통합 – herdr-ai-notify 플러그인을 설치하여 Herdr 관리 AI 세션에서 알림을 트리거할 수 있습니다.
• 사용자 지정 Webhook URL – JSON 페이로드를 수락하는 모든 HTTP 엔드포인트 추가 가능. UI에서 채널 이름을 지정하고 테스트할 수 있습니다.

권장 사용자

• 코드 생성, 데이터 분석 또는 장시간 실행되는 프롬프트를 위해 Claude, Gemini, Codex 등을 사용하며 모델 완료 시 알림을 받고 싶은 개발자.
• 몇 분에서 몇 시간 걸리는 LLM 기반 파이프라인을 실험하는 연구원.
• AI가 작동하는 동안 터미널 창을 숨겨두고 싶지만 상태는 파악하고 싶은 사용자.

---

TL;DR – AI CLI Complete Notify는 AI 어시스턴트 CLI를 모니터링하고, 선택적으로 네이티브 후크를 설치하며, 데스크톱, 사운드, 이메일, Telegram 또는 사용자 지정 Webhook을 통해 완료 알림을 푸시하는 크로스 플랫폼 도우미입니다. 장시간 실행되는 AI 명령을 사용하며 신뢰할 수 있는 "작업 완료" 알림이 필요한 모든 분께 유용합니다.