Mulmoterminal Notify

Which moments notify you, and how

Running several agents at once is what turns notifications into noise, so the defaults are deliberately narrow: only finished and waiting beep, and the other four are opt-in.

Ask what they actually want to be interrupted for before changing anything. "Turn on all six" is almost never the right answer.

The six moments

Two of these have caveats worth saying out loud:

• session-exited fires when you close a cell yourself. Closing goes through the same path, so someone who enables it will hear it on every deliberate close and think it is misfiring.
• pr-ci-failed is only seen while the roster is on screen. The phase poll doesn't run otherwise, so a failure that lands while the user is in another view is never noticed. It is not a background CI watcher; don't offer it as one.

Sound — global

Settings has a UI for this (Notification sounds), so use this skill when the user wants something the UI makes tedious — a different sound per moment, or per project.

{
  "soundKinds": ["finished", "waiting", "command-failed"],
  "sounds": { "waiting": "preset:coin", "command-failed": "preset:gong" },
  "soundFile": "/Users/you/sounds/done.mp3"
}

• soundKinds — which moments beep. Omit to keep ["finished", "waiting"]; [] for silence. Listing a kind here is what makes it audible at all — a sounds entry for a kind that isn't in soundKinds plays nothing.
• sounds — per-kind sound. A preset:<id> or an absolute path. A kind with no entry falls back to soundFile, and then to the built-in chime.
• soundFile — the fallback for every kind. Absolute path.

Presets: preset:chime · preset:coin · preset:cheep · preset:door · preset:gong · preset:magic · preset:meow.

The preset audio is fetched once from GitHub into ~/.mulmoterminal/sounds/ and served locally afterwards, so it keeps working offline — but the first play of a preset needs the network. If the user is offline and a new preset is silent, that is why; it isn't a config error.

Partial POST /api/config merge — write only the keys you are changing, and send each of them complete. sounds is an object, but it is replaced whole exactly as soundKinds is: posting {"sounds": {"waiting": "preset:coin"}} deletes every other kind's sound, with no warning and a successful response. Read the current sounds from GET /api/config, add your entry to that map, and send the merged map back.

Sound — per project

<project>/.mulmoterminal.json. Settings → Directory settings → Change here sets one directory's sound and per-kind sounds (a preset or a file in the directory); this skill is for setting it up across projects, or explaining what a moment plays: one repo that beeps differently so you know which one called you.

{ "sound": "./sounds/done.wav", "sounds": { "waiting": "preset:coin", "command-failed": "./sounds/bad.wav" } }

• sound — this directory's fallback for every kind.
• sounds — per-kind.
• Both accept either a preset:<id> or a relative file path. (Before 8.0.0 sound took a file path only and silently dropped a preset; a file written for that version still works.)
• A file path here must be RELATIVE to the project. Absolute paths and ../ escapes are rejected, and the resolved path is canonicalised so a symlink pointing outside the project is rejected too — a project you open must not be able to make the player read arbitrary files. This is the opposite rule from the global file, where paths must be absolute; pasting an absolute path into the project file is the most common mistake, and it fails silently.
• The file must exist, or the entry resolves to nothing. If it is gitignored, say that a colleague cloning the project gets silence, not an error.
• A per-kind sound still only plays if that kind is in the global soundKinds. A project cannot switch a moment on for itself.

Writing the file with your Write/Edit tool is itself the live-reload signal — there is no filesystem watcher. It applies immediately.