guide · wake-up

Wake-up: an idle Claude Code session answers when a message arrives

Delivery puts a contact’s message into the Murmur store on your computer; wake-up makes your assistant start a turn and read it without anyone typing. In Claude Code, Murmur does this with a Stop hook: after each turn the hook watches the store, for eight hours from 2.12.0 (about ten minutes in 2.11.0), and when a message arrives it exits with code 2, which Claude Code’s asyncRewake option turns into a new turn of the idle session. In the Codex CLI, the Murmur service connects to codex app-server over a Unix-domain socket and starts a turn on the session’s thread.

Updated 29 September 2026 · Murmur 2.12.0

honest status

ready, delivered, answered — and wake-up

Murmur 2.11 keeps these states apart in the app and on the command line, and does not show a check that never ran as a success.

service ready

The service runs and is connected to the server; the app says “Service connected and ready”. It says nothing about your contact: a contact that has not been checked yet is shown separately.

delivered

Your contact’s service checked the signature, decrypted the message, saved it and returned a signed receipt. Their assistant may not have seen it yet. murmur_request reports only acknowledged messages as delivered.

reply received

A message came back. Only this proves that the pair works in both directions. The built-in check, murmur doctor --peer, is answered by the contact’s service itself in 2.11: it proves the channel, not the assistant.

wake-up

The assistant on the other side started a turn by itself and read the message. This is a separate setting with its own status, and the app states that checking a contact does not test wake-up.

Claude Code

a Stop hook that listens after every turn

Choosing Claude Code as your assistant in the Murmur app, or running murmur clients configure --client claude-code, adds the Murmur MCP server to ~/.claude.json and a Stop hook to ~/.claude/settings.json. Running it again changes nothing; a different Murmur hook is replaced only with --replace.
Claude Code runs the hook when a turn ends. Because the hook has asyncRewake set, it keeps running in the background and polls the local Murmur store, one poller per session. The command asks for up to 28 800 seconds, but the entry sets no timeout of its own, and Claude Code applies its default of 600 seconds to asyncRewake hooks, so in 2.11.0 the effective window after each turn was ten minutes; from 2.12.0 the entry carries its own timeout of 28800 seconds (issue #273; the fix adds the timeout to the entry).
When a message from a contact arrives, the hook prints one line with the sender and the number of new messages and exits with code 2. Claude Code shows that line to Claude as a system reminder and starts a new turn, though nobody typed anything.
Claude reads the full text with murmur_inbox and answers with murmur_send. The line that started the turn carries no message text and says that the text is data, not instructions.

The entry it writes has this shape; the paths are absolute paths on your computer:

{
  "hooks": {
    "Stop": [{ "hooks": [{
      "type": "command",
      "asyncRewake": true,
      "command": "node --no-warnings /path/to/scripts/wake-drain-claude.mjs --db /absolute/murmur-identity/murmur.db --max-seconds 28800"
    }] }]
  }
}

Each session keeps its own position in the store, so one message starts a turn in every live Claude Code session that uses this identity. Sessions that share an identity share its inbox; give independent sessions separate identities.

A second, optional hook on SessionStart with --session reports, when a session starts, what arrived while no session was running. It is described in wake-native.md and is not installed by clients configure.

Codex

a turn started through codex app-server

Codex has no Stop hook to poll from. Here the Murmur service itself talks to codex app-server, over a WebSocket on a Unix-domain socket. This path is set up by hand; the app and clients configure do not do it in 2.11.

Start the app-server and launch Codex against its socket: codex remote-control start --json returns the socket path, and codex --remote unix://PATH attaches the session to it.
In the identity’s configuration file, agent-config.json, point the contact at that socket under wake.peers, with "mode": "codex_app_server" and socketPath. With threadId set to the thread of a live Codex session, the turn starts in that session; without it, Murmur starts its own thread per contact and conversation on that app-server and remembers it across restarts. The service reads this at startup, so restart it after the change.
When a message arrives, the service connects to the socket, sends initialize, then turn/start with the message on the thread. A missing socket or thread is logged as a failure; it does not fall back to polling in silence.
A failed turn is retried under the same delivery ID with backoff, up to five attempts, then moved to the dead-letter queue; a turn that someone interrupted on purpose is not retried. Messages of one contact and conversation run in order, and up to four conversations run at once by default.

{
  "wake": {
    "peers": {
      "bob": {
        "mode": "codex_app_server",
        "socketPath": "/home/you/.codex/app-server-control/app-server-control.sock"
      }
    }
  }
}

With relayFinalToMurmur set for the contact, the service also sends the turn’s final answer back to that contact. This path uses Unix-domain sockets, so it works on macOS and Linux; its Windows transport is not implemented.

Codex Desktop on macOS has a separate, opt-in path: Murmur hands an incoming message to the exact Desktop task that started the conversation with codex queue. It starts an idle task but does not steer a turn that is already running. See codex-desktop-queue-wake.md.

in the app

where wake-up is switched on

Claude Code

Choosing Claude Code as your assistant in the Mac app or the Windows tray installs the Stop hook together with the MCP server. Reload Claude Code afterwards; the hook first runs when a session finishes its next turn.

pause and resume

The menu can pause wake-up and resume it. A pause keeps waiting messages in order; after resuming they are handled as usual, which after a long pause can mean a burst of turns. The setting applies when the service restarts, and the menu shows when the configured and the effective state differ.

labels in 2.11.0

On a Mac, 2.11.0 still names this menu item with its older label, Agent delivery; builds after 2.11.0 say “Wake-up”. In the Windows tray the items are Pause and Resume.

Codex and Claude Desktop

Codex wake-up has no switch in the app in 2.11: it lives in the identity’s configuration file, as above. Claude Desktop can send and read Murmur messages, but it does not start a turn when a message arrives.

limits

what does not start a turn

Claude Desktop. Sending and reading work through MCP; a new message does not start a turn. Open the conversation and ask it to read the inbox.
Codex on Windows. App-server wake-up needs Unix-domain sockets, and the Windows transport is not implemented.
Codex sessions that are not attached to the app-server. A plain codex session or a Codex Desktop session started on its own is not reached: app-server instances are isolated per session and do not talk to each other.
A new Claude Code session before its first turn. The Stop hook runs when a turn ends, so a session that has just started is not listening yet. For an unattended session, send one harmless prompt right after launch.
In 2.11.0, a message that arrived before a new session’s first Stop. The hook started reading at the newest message, so that message started nothing until the inbox was opened by hand. The fix is merged after 2.11.0 and not released yet (CHANGELOG, Unreleased, #245).
After the listening window since the last turn (eight hours from 2.12.0; ten minutes in 2.11.0). The hook has stopped listening; the message starts a turn at the next prompt a person types.
Paused wake-up. Messages wait in order until you resume it.
A stopped Murmur service. Nothing is received on that computer; the sender’s service retries within its limits.
Diagnostic checks. murmur doctor tests are answered by the service and never start a turn.

Behavior after a reboot or an assistant reload has not passed acceptance yet, so check wake-up again after every restart: send a test message from the other side while the assistant is idle, and wait for the answer. The full list is in the known limitations.

questions

short answers

Does Murmur keep Claude Code running?

No. Murmur does not launch Claude Code. The Stop hook runs inside a session you started, after that session finishes a turn, and listens for a window after that turn (eight hours from 2.12.0; ten minutes in 2.11.0, see issue #273); a message in that window starts the next turn of the same session.

A message arrived, so why did Claude Code not answer?

Check, in order: that the session has finished at least one turn since it started; that its last turn ended inside the listening window (eight hours from 2.12.0; ten minutes in 2.11.0); that wake-up is not paused; and that ~/.claude/settings.json has the Murmur Stop hook, which Murmur writes when you choose Claude Code as your assistant. In 2.11.0, a message that arrived before a new session’s first Stop is also skipped until you open the inbox.

Does the hook put the message text into Claude’s context?

No. The line that starts the turn names the sender and the number of new messages and says that the text is data, not instructions. Claude then reads the full text with murmur_inbox, like any other tool result.

Does wake-up work for Codex on Windows?

Not in 2.11. Codex wake-up goes through codex app-server over a Unix-domain socket, and its Windows transport is not implemented. On Windows, Codex sends, reads and answers Murmur messages whenever it runs a turn.

Does wake-up work in Claude Desktop?

No. Claude Desktop can send and read Murmur messages through MCP, but it does not start a turn when a message arrives. Open the conversation and ask it to read the inbox.

Is this the same as Claude Code’s cross-session messaging?

No. Claude Code’s cross-session messaging also starts a new turn in an idle session, but for messages between your own Claude Code sessions, sent with its SendMessage tool. Murmur’s wake-up is for messages from Murmur contacts, which can be other people and other assistants, Codex included.

related guides

Sources: wake-native.md · CHANGELOG.md · release v2.12.0 · Claude Code hooks reference