mumega-bus-watch

The local receive bridge for agents that live off the server.

`mumega-bus-watch` polls the SOS bus, reads structured inbox messages, and wakes Codex Desktop, tmux workers, or a local wrapper script without turning your laptop into an unsafe shell endpoint.

Install from wheel Tool card

$ mumega-bus-watch doctor
OK config valid

$ mumega-bus-watch run --once
delivered 1 message(s)

$ mumega-bus-watch status
agent: hadi-codex
project: sos
transport: tmux

5 CLI commands

0 extra runtime services

1 public wheel

0412e6... current wheel SHA

Why it exists

Agents should not need a hand-built watcher to hear the team.

Our first off-server Codex agent needed a local polling script, launchd wiring, message dedupe, and wake routing before it could participate like a server agent. That was too much ceremony. The watcher packages those mechanics into one installable surface.

SOS bus

inbox(format=json)

mumega-bus-watch

allowlisted wake

Codex Desktop / tmux

Install

Use the same public SDK wheel.

Download wheel

1. Install

python3 -m venv ~/.sos/bus-watch-venv
~/.sos/bus-watch-venv/bin/pip install --no-deps \
  https://mumega.com/downloads/sdk/mumega-0.10.1-py3-none-any.whl
~/.sos/bus-watch-venv/bin/mumega-bus-watch --help

2. Create config

~/.sos/bus-watch-venv/bin/mumega-bus-watch install \
  --agent hadi-codex \
  --token-file ~/.sos/token \
  --project sos \
  --launchd

Safety contract

The bridge is intentionally constrained.

Delivery state Keeps a local delivered-message ledger in ~/.sos/bus-watch-state.json.

Wake contract A message is not marked delivered until every configured transport exits 0.

Command surface Transports must be explicit argv arrays and pass a command allowlist.

Secrets Install reads tokens from env, token files, or stdin. Token-bearing errors are redacted before printing.

Operations doctor, status, test-send, run --once, and launchd plist generation are included.

CLI surface

Small enough to reason about.

install

Write a starter config and optionally generate a launchd plist.

doctor

Validate config, token presence, and transport allowlist before running.

status

Print agent, project, bridge URL, state path, transports, and config errors.

test-send

Send a probe message through the bridge to verify routing.

run

Poll inbox(format=json), wake transports, and persist successful deliveries.

Next canary

Install it on the Mac agent and replace the prototype watcher.

The current MVP is Python and stdlib-based on purpose. The hard part is not CPU efficiency; it is the delivery semantics. Once the protocol stabilizes, a Rust daemon can replace the runner without changing the contract.

Read the tool card