Agent Toast

Claude Code / Codex CLI 훅 이벤트를 데스크톱 알림으로 띄우고, 클릭하면 알림을 띄운 터미널로 바로 돌아가는 앱.

한국어 | English

원본(hopoduck/agent-toast)이 Windows 전용이라 macOS 지원을 추가하려고 만든 fork입니다. 이 fork의 Releases는 macOS만 배포하며, Windows 빌드는 계획에 없습니다 — Windows는 원본을 사용하세요.

이 fork에서 수정한 것

• macOS 지원 추가 (기존 Windows 전용 → Windows + macOS 코드베이스, 배포는 macOS만)
  • crates/agent-toast-desktop/src/platform/로 OS별 코드 분리: win.rs(기존 win32.rs) / mac.rs(신규) / stub.rs(그 외 타깃)
  • 로컬 transport: Windows Named Pipe ↔ macOS Unix 소켓 (~/Library/Application Support/agent-toast/at.sock)
  • 싱글 인스턴스: Windows Mutex ↔ macOS flock
  • 포커스 감지(FR-2/FR-3): Windows SetWinEventHook ↔ macOS 400ms 폴링
  • 창 활성화: Windows SendInput+SetForegroundWindow ↔ macOS NSRunningApplication.activateWithOptions
  • 프로세스 트리 추적: Windows CreateToolhelp32Snapshot ↔ macOS ps -Ax -o pid=,ppid=
  • 알림음: Windows WinRT MediaPlayer/PlaySoundW ↔ macOS afplay
  • 시스템 폰트 목록: Windows GDI EnumFontFamiliesExW ↔ macOS NSFontManager
  • 작업 영역 계산에 macOS 메뉴바 인셋 보정 추가 (platform::cache_menu_bar_inset)
  • Tauri 번들 타깃에 app/dmg 추가 (기존 nsis)
• macOS 빌드 편의를 위한 build.command 추가 — Finder에서 더블클릭하면 pnpm/cargo 확인 → pnpm install → pnpm tauri build 실행
• Codex CLI 연동을 macOS에서도 지원 (기존 Windows 전용 → Windows + macOS)

기능

• 작업 완료 / 권한 요청 / 입력 대기 등 15가지 훅 이벤트
• 알림 클릭 시 알림을 띄운 터미널 창(Windows) / 앱(macOS)으로 포커스 이동
• 터미널로 포커스가 돌아오면 알림 자동 소멸, 이미 보고 있으면 알림 생략
• 알림 본문에 에이전트의 마지막 메시지 표시 (권한 요청 시 도구 설명)
• 원격 Linux 서버의 Claude Code 훅 알림을 HTTP로 수신
• 멀티 모니터 4코너 위치 선택, DPI 스케일 대응
• 알림음 on/off, 커스텀 사운드 파일 지원
• 라이트/다크 테마 연동, 토스트 디자인(바·폰트·밀도) 커스터마이즈
• 알림 표시/클릭/자동 소멸 통계 집계
• 한국어/영어 UI
• 자동 업데이트

설치

Releases

https://github.com/Craft374/agent-toast/releases/latest — macOS .dmg만 배포 (Windows는 원본 프로젝트 Releases 이용)

직접 빌드 (macOS)

요구사항: Node.js 18+, pnpm, Rust, Xcode Command Line Tools

build.command를 Finder에서 더블클릭 (또는 터미널에서 ./build.command)

결과물: target/release/bundle/macos/, target/release/bundle/dmg/

코드베이스 자체는 Windows 빌드도 여전히 가능하지만(pnpm tauri build, MSVC 툴체인 필요), 이 fork는 Windows 빌드를 테스트·배포하지 않습니다.

사용법

설정 창 열기:

agent-toast --setup       # macOS
agent-toast.exe --setup   # Windows

또는 시스템 트레이 아이콘 우클릭 → 설정. 설정 창에서 원하는 훅 이벤트를 켜면 자동으로 등록된다.

플랫폼	설정 파일
Claude Code	~/.claude/settings.json
Codex CLI	~/.codex/config.toml

작동 원리

• 최초 실행 시 앱을 띄우고, 이후 CLI 호출은 로컬 소켓으로 JSON만 보낸 뒤 즉시 종료 (단일 인스턴스)
• 포커스 변화를 실시간 감지해 알림을 자동으로 닫음
• --pid에서 프로세스 트리를 거슬러 올라가 알림을 띄운 터미널 창(Windows)/앱(macOS)을 찾음

원격 알림 (Linux 서버)

1. 데스크톱 설정 창 → 원격 알림 → HTTP 수신 활성화 (기본 포트 38787, 바인딩은 항상 0.0.0.0)
2. 서버에 agent-toast-send 설치 후 훅 등록:

curl -L https://github.com/Craft374/agent-toast/releases/latest/download/agent-toast-send-linux-$(uname -m) \
  -o ~/.local/bin/agent-toast-send
chmod +x ~/.local/bin/agent-toast-send

agent-toast-send init --url http://<desktop-ip>:38787 --dynamic [--hostname "prod"]

<desktop-ip>는 서버에서 데스크톱에 도달 가능한 주소(Tailscale, LAN, SSH -R). 해제는 agent-toast-send uninstall.

글로벌 통계 (익명)

알림 표시/클릭/닫힘 카운터와 설치 시 생성된 랜덤 ID만 집계 서버로 전송. 호스트명·경로·메시지 내용은 전송하지 않음. 설정 → 통계 탭에서 끌 수 있음.

기술 스택

Rust + Tauri (백엔드/네이티브) · Vue 3 + TypeScript (프론트엔드)

라이선스

MIT License