---
title: "Tell Kilobat when an agent waits or is done · Kilobat Recipes"
url: "https://kilobat.app/guides/recipes/connect-agent-hooks"
description: "Connect Claude Code, Codex, Gemini CLI or Cline hooks to kilobat agent-event, so that Kilobat knows when a run works, waits for you or is done."
---

Recipe

# Tell Kilobat when an agent waits or is done

Without hooks, Kilobat sees an agent only by its traffic and CPU. Hooks tell it the project, and when a run waits for you or is done.

Free in the app and the CLI · Checked: 29 October 2026

## In the app

1. Open Settings and find Awake & agents.
2. Turn on Keep the Mac awake while AI agents work.
3. Look at the session strip in the popover. Each agent run shows as a chip with its state.

## With the CLI

1. For Claude Code, add a command hook to `~/.claude/settings.json` under SessionStart, UserPromptSubmit, Notification, Stop, StopFailure and SessionEnd.

   ```
   kilobat agent-event --agent claude --stdin-json
   ```
2. For Codex, add this line to `~/.codex/config.toml`. It reports done only.

   ```
   notify = ["kilobat", "agent-event", "done", "--agent", "codex", "--json-arg"]
   ```
3. For Cline, install the Kilobat plugin.

   ```
   cline plugin install https://kilobat.app/agents/cline/kilobat.ts
   ```
4. Test a hook by hand. `--verbose` says what happened.

   ```
   kilobat agent-event start --agent claude --verbose
   ```
5. Read the recorded runs.

   ```
   kilobat sessions --days 1
   ```

## Through MCP

Connect the MCP server once with `claude mcp add kilobat -- kilobat mcp`. For other clients, see [the docs](https://kilobat.app/docs#agents). Then an agent can call these tools. Tools that change settings tell the agent to ask you first.

| Tool and arguments | What it does |
|---|---|
| `list_sessions` `{"days": 1}` | Runs with `project`, `state` (working, waitingForYou, done, stalled, networkFailed or failed) and the data used. |

## Good to know

- `kilobat agent-event` prints nothing and always exits 0, so it cannot break the agent.
- If the app is not running, the events wait in a small file that the app reads when it opens.
- Kilobat reads session IDs, folders and short status text. It never reads prompts or replies.
- Merge these hooks with the hooks that you already have.

## Sources

- [Kilobat docs: Connect agents](https://kilobat.app/docs#connect-agents)
- [Kilobat llms.txt: CLI and MCP reference](https://kilobat.app/llms.txt)

Sources checked on 29 October 2026. Man pages are the ones installed with macOS; open one with `man <name>` in Terminal.

## Related guides

- [Keep an agent running with the lid closed](https://kilobat.app/guides/recipes/agent-lid-closed): Closing the lid puts a Mac laptop to sleep.
- [Keep your Mac awake until a download finishes](https://kilobat.app/guides/recipes/keep-mac-awake-download): Kilobat keeps the Mac awake while transfers run.
- [Check the network before a big download in an agent](https://kilobat.app/guides/recipes/check-network-before-download): An agent can ask Kilobat if now is a good time for a large transfer.