| name | muxrun-doctor |
| description | Diagnose muxrun environment and runtime issues — missing tmux, stale daemon PIDs, leftover sessions, port conflicts, broken config. Use when "muxrun isn't working", commands hang or error out, or after an unclean shutdown / crash. Read-only by default; only takes destructive action with explicit user confirmation. |
muxrun-doctor
Run a top-to-bottom health check of the local muxrun setup and report findings. Suggest fixes; do not execute destructive cleanup without confirmation.
When to invoke
- The user reports muxrun "isn't working", commands hang,
up fails immediately, ps shows stale state, or daemons keep restarting.
- After a crash, system reboot, or
kill -9 of muxrun/tmux.
- Before filing a bug — to gather diagnostic info.
Checks (run in this order)
1. CLI presence and version
command -v muxrun and muxrun --version. If missing, refer to README.md install instructions.
2. tmux availability
command -v tmux and tmux -V. muxrun requires tmux. If absent, instruct install (brew install tmux / package manager).tmux ls 2>&1 — list all sessions. Note any muxrun-* sessions.
3. Config resolution
muxrun check from the user's current dir. If it fails, surface the specific error.- Report which config file was resolved (CWD walk-up, see
docs/config.md).
4. Daemon state
muxrun stores daemon artifacts under $TMPDIR/muxrun/ (macOS) or /tmp/muxrun/ (Linux fallback). Resolve $TMPDIR first.
ls -la "$TMPDIR/muxrun/" 2>/dev/null — list daemon-<group>.pid and daemon-<group>.log files.- For each PID file: read it, then
ps -p <pid> -o pid,stat,etime,command to check if the process is alive.
- Stale PID file: PID file exists but the process is gone. Note as a stale entry; suggest removing the PID file (do NOT remove without confirmation).
- Orphan daemon: process is alive but no corresponding tmux session (
muxrun-<group>) exists. Suggest kill <pid> after confirming.
- Mismatched daemon: process command line doesn't look like
muxrun _daemon .... Flag and ask the user.
5. tmux session vs config drift
- For each group in the resolved config, check
tmux has-session -t muxrun-<group> 2>/dev/null.
- For each existing
muxrun-* session not in the current config, flag as "leftover from a different config / worktree".
6. Daemon log scan
- For each
daemon-<group>.log in $TMPDIR/muxrun/, look at the tail (tail -n 100) for repeated restart loops, fsnotify errors, "too many open files", or panics.
- Report a one-line summary per daemon.
7. Port / resource hints (best-effort)
- If the user's config commands include obvious ports (e.g.,
:3000, --port 8080, PORT=), check lsof -nP -iTCP:<port> -sTCP:LISTEN 2>/dev/null for conflicts.
- Note: this is heuristic — only flag what is clearly relevant to the running config.
8. File descriptor / watch limits (when watch is enabled)
- macOS:
launchctl limit maxfiles and ulimit -n.
- Linux:
cat /proc/sys/fs/inotify/max_user_watches. fsnotify exhausts watches on large trees — recommend raising the limit or expanding exclude patterns when the count is low (< 524288 on Linux).
Output
Produce a structured report:
## muxrun doctor
[OK] muxrun v0.x.x
[OK] tmux 3.x
[WARN] Stale daemon PID: $TMPDIR/muxrun/daemon-backend.pid -> 12345 (no such process)
[FAIL] muxrun check: <error>
...
### Suggested actions
1. Remove stale PID: rm "$TMPDIR/muxrun/daemon-backend.pid" (needs confirmation)
2. ...
Action policy
- Read-only by default. Doctor diagnoses; it does not clean up.
- Confirm before destructive ops. Removing PID files, killing daemons, killing tmux sessions, raising kernel limits — all require explicit user "yes". Show the exact command before running it.
- Never
kill -9 muxrun / tmux without first trying graceful (muxrun down → kill <pid> → only then escalate).
Anti-patterns
- Don't invent fixes that aren't supported by what you observed.
- Don't suggest
pkill -f muxrun as a default — it can take down legitimate sessions in other worktrees.
- Don't remove
$TMPDIR/muxrun/ wholesale.
