idlebell
hjinhao066/idlebell
Notificações desktop quando seus agentes IA terminam de trabalhar
Ver no GitHubAgent daemon que monitora agentes de IA em execução nos terminais (Claude Code, Antigravity, etc.) e envia notificações desktop clicáveis quando terminam. Funciona em macOS e Windows, monitorando Terminal, tmux, Windows Terminal e terminais embarcados sem necessidade de plugins.
Instalação
npx convez-ai hjinhao066/idlebell1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Monitorar múltiplos agentes IA rodando em paralelo em tmux/terminais
- Receber alertas imediatos quando Claude Code finaliza tarefas longas
- Focar em outras janelas sem perder de vista o progresso dos agents
Veredito

Solução prática e bem pensada para quem roda múltiplos agentes IA em paralelo. Elimina a necessidade de ficar verificando terminais manualmente, oferecendo integração nativa em macOS e Windows sem exigir configuração dentro dos agents.
README
A tradução para o português deste README ainda está na fila.
🔔 idlebell
Rings when your AI agent finishes. A tiny background daemon that watches AI coding agents (Claude Code, Antigravity, Grok CLI) running in your terminals and sends a clickable desktop notification the moment one finishes and goes idle. Click the notification and you land in exactly the right terminal tab, tmux pane, or app window.
If you run several agents in parallel — a tiled tmux grid, a deck of terminal columns, a pile of background tabs — idlebell is the "your agent needs you" doorbell, so you can stop alt-tabbing to check on them.
How it works
idlebell polls the rendered screen text of your terminals (no shell hooks, no agent plugins, nothing to configure inside the agents). A small state machine per pane decides when to ring:
- Detect — pattern-match the screen to recognize a supported agent.
- Settle — wait until output stops changing for a few seconds, ignoring
live status lines (spinners, token counters,
esc to interrupt). - Idle check — require an agent-specific idle prompt to be on screen.
- Visibility check — never ring for a pane you are currently looking at.
- Ring — desktop notification with the agent's last meaningful output line; clicking it focuses the right window/tab/pane.
Sources monitored
| Platform | Source | Read via |
|---|---|---|
| macOS | Apple Terminal tabs | AppleScript history |
| macOS | tmux panes (e.g. inside Ghostty), attached or detached | tmux capture-pane |
| macOS / Windows | AgentDeck-style embedded terminals | spool files |
| Windows | Windows Terminal panes (visible tab) | UI Automation |
Known limitations, by design of the underlying platforms:
- Ghostty has no AppleScript API; idlebell can only see inside it through tmux. Native Ghostty splits without tmux cannot be read.
- Windows Terminal only exposes the currently visible tab via UI Automation; agents in background tabs ring when you next switch to their tab.
- Agent detection is regex-based against each agent's UI chrome; new agent versions occasionally need a pattern update (PRs welcome).
Install — macOS
Requires: macOS, Python 3 (system /usr/bin/python3 is fine), and
alerter (brew install alerter) or
terminal-notifier for notifications. tmux is optional.
git clone https://github.com/hjinhao066/idlebell.git
cd idlebell/mac
./install.sh
This copies four scripts into ~/.local/bin and registers a LaunchAgent
(com.idlebell.watch) so the daemon starts at login and stays alive. On first
run, grant the Automation permissions macOS asks for (the daemon reads
Terminal via AppleScript and the frontmost app via System Events).
# logs
tail -f ~/.local/share/idlebell/watch.log
# restart
launchctl kickstart -k "gui/$(id -u)/com.idlebell.watch"
# uninstall
./uninstall.sh # add --purge to also delete logs
Install — Windows
Requires: Windows 10/11, Python 3.10+ on PATH.
git clone https://github.com/hjinhao066/idlebell.git
cd idlebell\windows
powershell -ExecutionPolicy Bypass -File install.ps1
This installs the dependencies (uiautomation, windows-toasts, psutil),
copies the daemon to %LOCALAPPDATA%\idlebell\app, and registers a Scheduled
Task that runs it at logon with no console window.
# logs
Get-Content $env:LOCALAPPDATA\idlebell\watch.log -Tail 20 -Wait
# restart
Stop-ScheduledTask idlebell; Start-ScheduledTask idlebell
# uninstall
powershell -ExecutionPolicy Bypass -File uninstall.ps1 # add -Purge for logs too
Integrating your own terminal app
Any app with embedded terminals (Electron + xterm.js, etc.) can join by dumping each pane's screen to a spool file every couple of seconds — that's the whole protocol. See docs/agentdeck-protocol.md for the rules and a reference snippet.
Supported agents
- Claude Code
- Antigravity (
agy) - Grok CLI
Adding one is a matter of appending a detect + idle pattern set to the
AGENTS table at the top of the daemon (mac/bin/idlebell-watch and
windows/idlebell_watch.py).
License
MIT
中文说明
idlebell:AI agent 跑完任务时给你响铃。
一个常驻后台的小守护进程,监控终端里运行的 AI 编程 agent(Claude Code、 Antigravity、Grok CLI)。当某个 agent 结束任务进入空闲时,弹出系统通知, 内容是它最后一行有效输出;点击通知直接跳转到对应的终端标签页 / tmux 窗格 / 应用窗口。适合同时开多个 agent 并行干活的工作流(tmux 网格、多列 deck、 一堆后台标签页),不用再来回切窗口盯进度。
- macOS:监控 Apple Terminal、tmux(含 Ghostty 内的 tmux 网格,分离的
session 也监控)、AgentDeck 类内嵌终端(spool 文件协议)。安装:
cd mac && ./install.sh(需要brew install alerter)。 - Windows:通过 UI Automation 监控 Windows Terminal(当前可见标签页),
spool 文件协议监控 AgentDeck。安装:
cd windows,以 PowerShell 运行install.ps1(需要 Python 3.10+)。
原理:轮询终端的屏幕文本 → 正则识别 agent → 等输出稳定(忽略转圈动画和 计时器状态行)→ 确认出现空闲提示符 → 你正在看的窗格不响铃 → 发可点击通知。 无需在 agent 或 shell 里装任何插件。