Get notified when Gemini CLI finishes (macOS)

Gemini CLI can grind through a task for minutes and then just… sit there, done, while you're in another window. Here are your options, from a one-line shell trick to a full watcher, honestly compared.

Option 1 — shell chaining (one-shot runs, free)

If you run Gemini non-interactively with -p, the shell already knows when it's done. No config needed:

gemini -p "refactor the parser" ; afplay /System/Library/Sounds/Glass.aiff

Honest limits: this only works for one-shot prompts — in an interactive session the process doesn't exit between turns, so nothing plays. And the terminal bell tells you nothing about whether it worked.

Option 2 — Gemini CLI's official hooks (DIY, free)

Gemini CLI supports lifecycle hooks in ~/.gemini/settings.json (official reference). The AfterAgent event fires when the agent finishes a turn — a minimal example that plays a sound:

{
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}

Honest limits: one sound for every outcome — no distinction between finished, failed, and waiting-for-permission (you'd wire Notification separately for that); nothing tells you which session; and settings.json also holds your theme and other Gemini settings, so merge carefully rather than pasting over the whole file.

Option 3 — a watcher that treats Gemini CLI as one of your agents

Sleepwing (free beta) merges its hooks into ~/.gemini/settings.json for SessionStart, BeforeAgent, BeforeTool, AfterTool, Notification, AfterAgent and SessionEnd — reversibly, preserving your existing settings and unrelated hooks — and puts one pet on your desktop that:

distinguishes working / waiting-for-you / finished / failed, per session;
brings you back to the exact terminal tab with one click, and covers your other agents too (Claude Code, Cursor, Codex, OpenCode, TRAE, pi) with the same pet;
turns agent work time into small real breaks — paused the moment Gemini waits on you;
makes zero outbound network requests. This matters more here than usual: Gemini's hook payloads can contain prompts, tool inputs, and responses. Sleepwing discards all of that locally before anything moves, keeping only the provider, an opaque session ID, the phase, a timestamp, a bounded task label, and a local resume route. Grep the source.

⬇ Download the notarized beta (macOS 14+, Apple Silicon)

Pick by situation: scripted one-shot gemini -p runs → shell chaining is enough, don't install anything. Comfortable with JSON and only Gemini → the DIY hook. Multiple agents a day, or you want failed and waiting-for-you to sound different from done → that's what Sleepwing is for.

中文速览

Gemini CLI 跑长任务结束时不会主动提醒你。方案：一次性任务直接用 shell 串联 gemini -p "…" ; afplay …（交互式会话无效）；或在 ~/.gemini/settings.json 里给官方 AfterAgent Hook 挂音效（上面有例子，注意与已有设置合并、不要整体覆盖）；或用 Sleepwing 桌宠——可逆安装官方 Hooks，区分「工作中/等你/完成/失败」，一键跳回终端标签页，还同时看管 Claude Code、Cursor、Codex 等其他 Agent。Gemini 的 Hook 载荷可能包含提示词和代码，Sleepwing 在本地全部丢弃、零外联。免费 Beta。