# 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 pi install npm:@mu-crew/murmur # the agent-side extension, as a pi package ``` 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. 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. CLIs from 1.4.0 and earlier lack the refusal, so upgrade the CLI first. ### 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. ## 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. Codex, opencode, and the Cursor CLI have no such hook — they run a command when something happens — so they use `murmur notify`, which 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 '