# Cmux Diagnostics

Run end-user cmux diagnostics.

- Repository: https://github.com/manaflow-ai/cmux (28635 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -a claude-code -y`
Codex: `npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -a codex -y`
Cursor: `npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -a cursor -y`
Gemini CLI: `npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -a gemini-cli -y`

## Description

Run end-user cmux diagnostics. Use when cmux hooks, notifications, session restore, settings, browser automation, socket access, CLI control, or agent resume behavior is not working, or when the user asks for a cmux health check, doctor report, or support-safe debug summary.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```bash
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

The rest: https://github.com/manaflow-ai/cmux/blob/HEAD/skills/cmux-diagnostics/SKILL.md