cmux Diagnostics

Collect and interpret support-safe cmux diagnostics for end users. Default to read-only checks. Never dump hook config files, session stores, prompt logs, tokens, or environment secrets.

Quick report

Run the bundled read-only script first, from whichever install path exists:

skills/cmux-diagnostics/scripts/cmux-diagnostics            # cmux checkout
~/.agents/skills/cmux-diagnostics/scripts/cmux-diagnostics  # installed skill
~/.codex/skills/cmux-diagnostics/scripts/cmux-diagnostics   # Codex-only skills.sh install

Add --include-context only when workspace names, cwd paths, and current cmux identifiers are relevant to the reported issue.

What to check

1. CLI and socket health: command -v cmux, cmux ping, cmux capabilities --json. If socket commands fail, check whether the agent is running inside a cmux terminal and whether socket automation is enabled.
2. Settings health: cmux-settings validate and cmux-settings get terminal.autoResumeAgentSessions (from ~/.agents/skills/cmux-settings/scripts/, or ~/.codex/skills/... for a skills.sh install). When terminal.autoResumeAgentSessions is false, cmux restores panes but does not resume saved agent sessions.
3. Hook installation: cmux hooks setup --agent codex, --agent opencode, or bare cmux hooks setup (installs supported agents found on PATH, skips missing ones). Run install or uninstall commands only after the user agrees.
4. Session restore evidence: ls -lh ~/.cmuxterm/*-hook-sessions.json 2>/dev/null. Missing stores usually mean the agent has not run inside cmux since hooks were installed, hooks are disabled, or the integration does not support resume capture.
5. Notification path: cmux notify "cmux diagnostic test", only when the user is ready for a visible test notification.

Interpretation