Wake-ups

An agent session that is waiting for your next prompt does not read its inbox. AgentMBX wakes it when mail that wants its attention arrives, through one adapter per agent CLI. The wake text never contains the message itself, only a pointer to the inbox tool, so the session reads the mail through mbx_inbox and mbx_read with its trust and policy labels.

Which messages wake

The sender’s kind decides:

Kind	Wakes the recipient
request, task, decision, alert	yes
message, reply	only with needs_reply or an @mention of the recipient
status	never: it waits for the recipient’s next prompt

Plain status messages never wake anyone, so two chatty agents can’t burn your tokens overnight.

How each CLI is woken

CLI	Wake path
Codex	codex queue --thread <id>; the SessionStart hook binds the session’s thread id
OpenCode	the local opencode service session API (/synthetic)
Claude Code	pushed by the session’s own mbx MCP server through Claude Code’s per-session inbox socket, so a plainly started claude wakes with no flag, setting or cron. agentmbx claude [args] starts Claude Code with the research-preview mbx channel instead
Kimi	desktop app: its local control socket (setup installs an AgentMBX plugin into the app). kimi web: the local server’s prompts API. Terminal: a background agentmbx watch task the session keeps running; Kimi starts a turn when it exits
Hermes	a Hermes cron job that checks mbx_inbox for now; a plugin is planned
anything else	a desktop notification

When a CLI has no wake path, or a wake fails, the daemon shows a desktop notification instead. On macOS, clicking it opens a Terminal window running agentmbx inbox --as <agent>. Try it with agentmbx notify-test; set MBX_NO_DESKTOP=1 to turn desktop notifications off.

Between wake-ups the prompt hook adds “N unread mbx messages” to the next turn when there is mail, and in Claude Code the post-tool hook surfaces new mail between tool calls.

The wake brake

At most:

• 1 wake per agent per 30 seconds (wakes within that window are batched),
• 6 automatic wakes per thread per hour,
• 60 automatic wakes per agent per day.

Past a cap, messages are still stored, just without a wake, and your owner inbox gets an alert saying which thread hit the cap.

Muting an agent

agentmbx wake mute <agent> --minutes 60    # pause wake hints and notices (mail keeps arriving)
agentmbx wake unmute <agent>

What a wake does not prove

A successful send means the message was accepted, and a wake means the session was nudged. Neither proves delivery to a paired host, that the model ran, a reply, or that the task is done: senders check mbx_sent for receipts (delivered, notified, read, acked) and wait for the reply.