Agent alerts
Long agent runs shouldn’t need babysitting. Agent alerts watch your AI CLI session and fire the moment the agent finishes a turn or stops to ask for input — so you can go do something else.
What fires
Pick any combination in Settings (⌘,) → Alerts:
- Dock bounce — the icon bounces until you come back
- Sound — an audible ping
- Bring to front — the terminal window surfaces above whatever you’re doing
Supported agents
Terminal Candy watches nine agents. Enable each with a single toggle in Settings → Alerts — no manual config editing.
| Agent | How it’s watched |
|---|---|
| Claude Code | Hook |
| Codex CLI | Log poll |
| Copilot CLI | Hook |
| Gemini CLI | Log poll |
| Cursor Agent | Hook |
| CodeBuddy | Hook |
| Kiro CLI | Hook |
| Kimi CLI | Hook |
| OpenCode | Plugin |
Hook agents get a tiny turn-complete hook written into their own config (e.g. Claude Code’s ~/.claude/settings.json Stop/Notification events). Toggling off removes it cleanly. If another tool already owns the hook slot, Terminal Candy wraps it transparently rather than clobbering it.
Log poll agents (Codex, Gemini) don’t expose hooks, so Terminal Candy tails their session logs (about every 1.5 s) and detects the turn-complete record — e.g. Codex’s task_complete event.
Plugin (OpenCode) registers a small plugin in opencode.json.
In every case the agent itself runs completely unmodified — the hook/poll only observes the “I’m done” signal.
Setup
- Settings (⌘,) → Alerts
- Toggle on the agents you use. A toggle only sticks if the agent is actually installed (Terminal Candy checks for its config directory).
- Choose your alert style — bounce, sound, bring-to-front.
- Run your agent in any Terminal Candy session and step away.
Alerts fire based on the agent’s own signals, so they work no matter which Terminal Candy tab or window the agent runs in.
Notes & limits
- Alerts tell you the agent finished or stopped for input — Terminal Candy doesn’t read, log, or transmit your session content.
- Enabling the Claude Code alert writes a hook entry to
~/.claude/settings.json; disabling removes exactly that entry and nothing else. - If an agent’s toggle won’t turn on, the agent’s config directory probably doesn’t exist yet — run the agent once first.
- Something not firing? See Troubleshooting or email support.