# Setup Wire murmur after `npm install -g @mu-crew/murmur`. Selling and surface overview: [README](../README.md). Hard ssh cases: [SSH.md](../SSH.md). ## Per-node init On every node that runs agents: ```bash murmur init # this node's identity, and hook entries pi install npm:@mu-crew/murmur # the agent-side extension, as a pi package ``` `murmur init` also writes the `murmur hook` entries for each hook harness set up on the node (see [below](#claude-code-codex-cursor-cli-and-muse-code-murmur-hook)). Run it again after an upgrade; a second run changes nothing. pi loads the extension from the package's `pi` manifest. The CLI and the extension are two installs of the same package, so upgrade them together: ```bash npm i -g @mu-crew/murmur@latest pi update npm:@mu-crew/murmur # then /reload running agents ``` Both share one store, in `~/.local/state/murmur2` (`$XDG_STATE_HOME/murmur2` when that is set; `MURMUR_STATE_DIR` moves it). When the schema changes, the newer side rebuilds the store and the older side refuses it rather than rebuilding it back: a CLI verb prints `written by a newer murmur` and exits 4 (`notify` and `clear`, which run from hooks, stay silent), the dash shows the message, and an older extension records nothing until it is upgraded. An extension that already had the store open when a newer CLI rebuilt it goes stale (its agent drops out of the view) until it reloads. 1.x builds keep their own directory (below). ### Coming from murmur 1.x 2.x keeps its state in `~/.local/state/murmur2`, not 1.x's `~/.local/state/murmur`: 1.x refuses the store the hook harnesses need, so the two cannot share one. The first 2.x command copies the node's `identity.json` (the same `host_id`, so peers still know it) and the old store's peers. It never writes to the old directory, so a 1.x murmur keeps working there, but the two do not see each other's agents: upgrade the CLI and the pi package together, then `/reload` running pi agents. Nothing is migrated under `MURMUR_STATE_DIR`. Once nothing runs 1.x, remove `~/.local/state/murmur`. ### Coming from `murmur link pi` The old `link pi` wrote a shim at `~/.pi/agent/extensions/murmur.ts`. Left in place next to the package, pi loads the extension twice and every event is reported twice. In this order: ```bash pi install npm:@mu-crew/murmur # once: registers the package murmur pi migrate # report only murmur pi migrate --apply # move the shim aside; nothing is deleted ``` Only a file byte for byte equal to a shim `link pi` generated (its two generated paths aside) is moved, into `~/.pi/agent/disabled/`, which pi does not read. A `link pi --copy` install, the inlined copy v0.1 `link pi` wrote, or an edited file is reported and left for you: move it aside yourself. `MURMUR_PI_HOME` changes the home directory it starts from. Running agents keep the old extension code until they restart. Order matters: without `murmur init` the extension loads and records nothing. Agents must run **inside tmux**. A pane is the address; without one there is nothing to jump to. ## tmux focus hooks Looking at a finished agent clears its badge. On every node, in `.tmux.conf`: ```tmux # Run murmur only when the pane, its window or its session shows a badge. %hidden MURMUR_ATTN="#{||:#{m/r:^(done|blocked|error|crashed)$,#{@murmur_pane_state}},#{||:#{m/r:^(done|blocked|error|crashed)$,#{@murmur_window_state}},#{m/r:^(done|blocked|error|crashed)$,#{@murmur_session_state}}}}" %hidden MURMUR_CLEAR="run-shell -b 'murmur clear --pane #{pane_id}'" set-hook -g after-select-pane "if -F '$MURMUR_ATTN' \"$MURMUR_CLEAR\"" set-hook -g after-select-window "if -F '$MURMUR_ATTN' \"$MURMUR_CLEAR\"" set-hook -g client-session-changed "if -F '$MURMUR_ATTN' \"$MURMUR_CLEAR\"" ``` The gate skips a Node start on switches with nothing to acknowledge. Window and session states count too, so orphan badges (from a pane that is gone) still clear. These are per node and not optional. `murmur clear` is what acknowledges an attention request. A node's own snapshot is what every peer reads — without these hooks, finished agents stay `done` in every peer's list. Verify with `tmux show-hooks -g`. `set-hook` accepts a name your tmux does not have and exits 0, so a wrong name fails silently. Pass the pane id explicitly: hooks run in the tmux server, where `$TMUX_PANE` is unset. Without it, a window holding an agent and a shell clears when you focus the shell. Focus can only cancel attention. It cannot stop a running agent or alter what the agent reported about itself. A focus hook needs no socket: it runs inside the server whose pane it names. From outside that server, name it as `murmur pane` does, with `murmur clear --pane %N -L ` or `-S `; mu does this to acknowledge a failed turn on its own tmux server before retrying it. A hook harness's next prompt clears that pane's `error` and `done` by itself. ## Side panel Bind the side panel in `.tmux.conf`: ```tmux bind C-m run-shell "murmur sidepanel" ``` Then press `prefix + C-m` to toggle it for the current window. This key is free in tmux's default prefix table. `prefix + m` and `prefix + M` are not free: tmux uses them to set and clear a pane mark. The panel opens on the left at 25 percent of the window width clamped to 25–40 columns, then shrinks to fit its widest line (never below 16 columns). It spans the full viewport even when the existing layout is nested, and takes focus. Toggling it again removes only that window's panel. Press `j` or `Down` to select the next agent, and `k` or `Up` to select the previous agent. Press `g` or `Home` to select the first agent, and `G` or `End` to select the last agent. Press `?` to show all panel keys. Press `?` or `Escape` to close the help panel. Press `c` to toggle compact one-line rows. With the mouse, click a row to select it, double-click it to jump to that agent, and scroll the wheel to move the selection. The side panel and dashboard share this compact setting, along with the saved sort and visibility settings. ## Harnesses other than pi pi reports in-process through the extension. Claude Code, Codex, the Cursor CLI (`cursor-agent`) and Muse Code report through `murmur hook`, which gives them ownership of their pane, `running` and `idle`, `blocked`, and the last turn's text. The rest — opencode, and Codex or the Cursor CLI set up the older way — use `murmur notify`. ### Claude Code, Codex, Cursor CLI and Muse Code: `murmur hook` `murmur init` writes these entries for you: ```bash murmur init # every harness whose config directory exists murmur init --hooks cursor-agent # also one not set up yet (or: all) murmur init --no-hooks # identity only ``` It writes `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json` and the `hooks` key of `~/.config/muse/settings.json`, for each harness whose directory (`~/.claude`, `~/.codex`, `~/.cursor`, `~/.config/muse`) exists. Those files are shared with mu, museum, muzzle and your own hooks, so murmur touches only handlers whose command starts with `murmur`: it adds the missing ones, sets Muse's `Interrupt` to `async`, and removes its own stale ones (a duplicate, a `murmur` handler under a filtering matcher or on an event it does not hook, the Cursor CLI's older `murmur notify` entry). Everything else stays where it was. A file already right is not rewritten, a symlinked file keeps its link, and a file that is not valid JSON is reported and left alone. A command that runs murmur by absolute path is yours, not murmur's: replace it with `murmur` on `PATH`, or `init` adds a second one. `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, when set, move Claude Code's and codex's files (`$CLAUDE_CONFIG_DIR/settings.json`, `$CODEX_HOME/hooks.json` and `config.toml`) for `init` and `doctor` as they do for the harnesses, muzzle and museum. Muse's and the Cursor CLI's stay under the home directory. `murmur doctor` checks the same entries: drift (a missing event, a stray or non-async handler, an unreadable file) is a problem, and a harness set up with no murmur entries is an observation. Both name `murmur init` as the fix. Once codex has these hooks, an older `notify` line in `~/.codex/config.toml` that runs murmur reports every finished turn a second time. murmur does not edit that file: `init` warns and `doctor` reports a problem until you remove the line. By hand, run `murmur hook claude` (or `murmur hook codex`) for each hooked event. The payload arrives on stdin and names its own event, so one command serves them all. Claude Code, in `~/.claude/settings.json`: ```json { "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "Notification": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "StopFailure": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }], "SessionEnd": [{ "hooks": [{ "type": "command", "command": "murmur hook claude" }] }] } } ``` Codex takes the same shape in `~/.codex/hooks.json`, with `murmur hook codex`, for `SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `Interrupt` and `SessionEnd`. Codex asks you to trust new or changed hooks once, including the ones `murmur init` writes. Drop the `notify` line from `~/.codex/config.toml` when you add these, or a finished turn is reported twice. The Cursor CLI, in `~/.cursor/hooks.json` (or a project's `.cursor/hooks.json`), with `murmur hook cursor-agent`: ```json { "version": 1, "hooks": { "sessionStart": [{ "command": "murmur hook cursor-agent" }], "beforeSubmitPrompt": [{ "command": "murmur hook cursor-agent" }], "afterAgentResponse": [{ "command": "murmur hook cursor-agent" }], "stop": [{ "command": "murmur hook cursor-agent" }], "sessionEnd": [{ "command": "murmur hook cursor-agent" }] } } ``` `afterAgentResponse` carries the turn's text and may land after `stop`; murmur pairs the two by the turn's `generation_id`. An Escape reads `idle`, and the `error` stop cursor-agent sends after it is dropped. The Cursor CLI has no permission hook, so its pane never reads `blocked`. `murmur hook cursor-agent` replies `{}` on stdout: the CLI treats empty stdout as a failed hook (`empty_stdout`) and tracking never sticks. Replace the `murmur notify --source cursor` entry below when you add these. Muse Code, under the `hooks` key of `~/.config/muse/settings.json` (or a project's `.muse/hooks.json`), in Claude Code's shape with `murmur hook muse`, for `SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `StopFailure`, `Interrupt` and `SessionEnd`. `Interrupt` must be declared asynchronous, and only this settings route delivers it; a Claude-format plugin cannot subscribe to it: ```json { "hooks": { "Interrupt": [ { "hooks": [{ "type": "command", "command": "murmur hook muse", "async": true }] } ] } } ``` Muse runs its hooks with a cleared environment (no `$TMUX`, none of mu's variables), which murmur does not need: it places the event by walking the hook's process chain to the tmux server, and names a mu worker from mu's anchor file. Do not hook `PreToolUse` or `PostToolUse`: they fire on every tool call and carry no state murmur uses. The hook prints nothing and always exits 0, so a murmur problem never blocks a turn. The agent must run in a tmux pane; a hook whose process chain does not reach a tmux server writes nothing. Events wait in a per-pane inbox under `~/.local/state/murmur2/inbox` (the home path whatever `XDG_STATE_HOME` says, since Muse's hooks never see it) until a reader (`murmur status`, the dash, `murmur pane`) applies them. An agent counts as crew when mu started it (its anchor file), or when the hook sees `MU_MANAGED_AGENT=1` or `MU_AGENT_NAME`. A worker mu starts on a remote host for a pane on this one carries a remote key (in its anchor, or `MU_REMOTE_KEY`). Its hooks write to that host's remote area instead of its inbox, so it never appears in the host's own `murmur status`; mu reads it with `murmur pane --remote --json` on that host. ### pi on mu's `hooks` channel With `MU_PI_CHANNEL=hooks` in its environment, murmur's pi extension stops using the store: it writes inbox events like the hooks above and never claims the pane or loads a native module. Set it only for a pi build that cannot load murmur's store; mu then drives that pi like the harnesses above. ### `murmur notify` Harnesses with no hook murmur maps run a command when something happens, and `murmur notify` records an attention request for the pane it runs in. This path is attention only: no ownership, no `running`/`idle`, no crash detection. Unrecognised events become `blocked`, so a new harness still puts a row in front of you. A request counts as crew, not yours, when the hook's environment has `MU_MANAGED_AGENT=1` or `MU_AGENT_NAME`, which mu sets on the agents it places. The hook inherits them from the harness, so a wrapper that clears the environment (`env -i`) makes a mu worker count as yours. ### Codex ```toml # ~/.codex/config.toml notify = ["murmur", "notify", "--source", "codex"] ``` Do not wrap with `sh -lc` alone. Codex appends the event JSON as one more argument, and `sh -lc '