cmux-diagnostics

Collects and interprets support-safe diagnostics for end users of cmux, covering hooks, notifications, session restore, settings, browser automation, socket access, CLI control, and agent resume behavior. It is used when one of those areas is not working or when the user asks for a cmux health check, doctor report, or support-safe debug summary. The skill defaults to read-only checks and deliberately avoids dumping hook config files, session stores, prompt logs, tokens, or environment secrets, summarizing file presence, size, modified time, and marker presence instead of contents.

The recommended starting point is the bundled read-only diagnostic script, located under the cmux checkout or an installed skill path, including a Codex-only skills.sh install. An --include-context flag is used only when workspace names, cwd paths, and current cmux identifiers are relevant to the reported issue. Beyond the quick report, the skill enumerates specific checks: CLI and socket health via command -v cmux, cmux ping, and cmux capabilities --json; settings health via the cmux-settings validate and get commands, noting that when terminal.autoResumeAgentSessions is false cmux restores panes but will not automatically resume saved agent sessions; hook installation via cmux hooks setup for codex, opencode, or all agents on PATH; session-restore evidence by listing the hook-sessions JSON files under ~/.cmuxterm; and the notification path via cmux notify, used only when the user is ready for a visible test.

An interpretation section explains common signals, such as cmux not found meaning the CLI is absent or off PATH, cmux ping failing meaning the app is unreachable or automation access is disabled, missing CMUX_WORKSPACE_ID or CMUX_SURFACE_ID indicating the command is running outside a cmux terminal, and a hook config existing without a session store meaning a supported agent has not run inside cmux since hooks were installed. Operating rules keep the skill read-only until the user asks to fix something, never print secrets, prefer narrow fixes such as cmux hooks setup --agent codex over reinstalling everything, run install or uninstall commands only after the user agrees, and rerun the diagnostic script after a fix to report the changed lines.