What does this skill do, and when should you use it?
cmux-diagnostics is a skill shipped in the manaflow-ai/cmux repository for health-checking cmux, a Ghostty-based macOS terminal for AI coding agents. It runs a bundled read-only script first, then walks through CLI/socket health, settings, hook installation, and session restore evidence. It explicitly forbids dumping hook configs, session stores, prompt logs, tokens, or environment secrets, so its output is safe to paste into a support request. Fix actions such as installing hooks only run after the user agrees.
- Runs the bundled read-only script skills/cmux-diagnostics/scripts/cmux-diagnostics from the checkout or installed path, optionally with --include-context to show workspace names and cwd paths
- Checks CLI and socket health via command -v cmux, cmux ping, and cmux capabilities --
- Validates settings with cmux-settings validate and reads terminal.autoResumeAgentSessions
- Checks hook installation (cmux hooks setup --agent codex, etc.) and whether ~/.cmuxterm/*-hook-sessions. files exist
- Sends a cmux notify test notification once the user is ready for a visible test
- Interprets results against a symptom table and reruns the script after fixes to report changed lines
- A developer running Claude Code or Codex inside cmux finds that agent sessions are not auto-resuming after relaunch
- A user configured notification hooks but never sees notification rings or desktop notifications and needs to know if hooks and the socket are healthy
- Someone preparing a bug report wants a support-safe debug summary that excludes tokens and raw session data
- A user suspects a broken ~/.config/cmux/cmux. and wants settings validated before chasing other symptoms
- A Codex user who installed the skill via skills.sh runs diagnostics from the ~/.codex/skills/ path
- Linux or Windows users: cmux itself is macOS-only, so there is nothing to diagnose without it
- People troubleshooting other terminals such as plain tmux or zellij; this skill covers only cmux's hooks, notifications, settings, and session restore
How do you install this skill?
- The referenced bundled script skills/cmux-diagnostics/scripts/cmux-diagnostics is not present in the evidence; its read-only behavior and safety cannot be statically verified — manually review the script before use.
- Repository license metadata is NOASSERTION and the repo mixes GPL/BUSL licensing; confirm the skill files' license attribution before enterprise use.
- The skill depends on the cmux CLI and macOS app, and its docs/distribution (cmux.com, GitHub Releases) may be unreachable from mainland-China networks; Chinese-language support is undeclared.
- All scores are based on static source reading (confidence: low); no scripts or commands were executed.
- Shell / CLI
- Local filesystem
cmux CLI (macOS app installed and running)cmux-settings skill scripts
The skill ships in the cmux repository's skills/ directory; SKILL.md lives at skills/cmux-diagnostics/. For a Codex-only skills.sh install, scripts land under ~/.codex/skills/cmux-diagnostics/scripts/; the general installed path is ~/.agents/skills/cmux-diagnostics/scripts/. No explicit install commands are documented in the source, so none should be invented.
git clone https://github.com/manaflow-ai/cmux.git
cd cmux
ls skills/cmux-diagnostics/How do you use this skill?
Once installed, send your agent any of these to trigger it:
- My cmux hooks are installed but notifications never fire — run a cmux health check
- Codex sessions aren't resuming after I relaunch cmux; give me a doctor report
- Generate a support-safe cmux debug summary with no secrets so I can send it to official support
- cmux ping is failing — help me figure out whether it's the socket or my settings
The skill triggers when the user reports cmux hooks, notifications, session restore, settings, browser automation, socket access, CLI control, or agent resume not working, or asks for a health check / doctor report. Flow: run the diagnostic script first (add --include-context only if workspace names and paths matter), then work through the checklist — CLI/socket, settings, hooks, session store files, notifications. Stay read-only until the user asks for a fix; after fixing, rerun the script and report the changed lines.
skills/cmux-diagnostics/scripts/cmux-diagnostics
~/.agents/skills/cmux-diagnostics/scripts/cmux-diagnostics --include-context
cmux hooks setup --agent codexWhat are this skill's strengths and limitations?
- Read-only by default and explicitly bans printing tokens, session JSON, and raw hook files, making reports safe to share
- Ships with a diagnostic script and a symptom-to-cause interpretation table
- Coverage spans cmux's most common failure surfaces: CLI/socket, settings, hooks, session restore, notifications
- Requires a working, running cmux install on macOS plus the companion cmux-settings skill scripts
- A missing session store yields only candidate causes (agent never ran in cmux, hooks disabled, resume capture unsupported), not a definitive verdict
- The notification test requires the user to be present to see it, so it does not fit unattended runs
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Diagnostics this page | 51 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Shared Behavior Rules | 48 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Settings Management Skill (cmux-settings) | 58 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux-browser: Browser Automation Skill for cmux | 60 · Recommended | ★ 28k | 1d ago | NOASSERTION |
The source offers no direct competitor comparison for a diagnostics tool; regarding tmux, the README positions tmux as a multiplexer inside any terminal while cmux is a native macOS app with a GUI and socket API — this skill diagnoses the latter only.
How did FollowSkills review this skill?
Skill defaults to read-only checks, forbids dumping hook configs, session stores, tokens, or secrets, and gates fix commands (hooks setup/uninstall) on user agreement; data-flow disclosure is good. Deducted because the bundled cmux-diagnostics script itself is not present in evidence, so read-only behavior is unverifiable; publisher unverified and license metadata NOASSERTION leaves attribution incomplete.
Instructions are self-consistent with three fallback install paths, step-by-step checks, and a systematic interpretation table (CLI missing, ping failure, missing env vars, etc.), giving above-average failure feedback. Deducted because the script body is absent with no tests or reproduction evidence; static anchors cap this at 10; fallback-path behavior in mismatched environments is not fully defined.
Frontmatter enumerates precise trigger scenarios (hooks, notifications, session restore, settings, CLI health, doctor report); audience is clear (macOS + cmux users). Deducted for thin non-fit boundaries and no statement on Chinese support or mainland-China reachability given dependence on cmux.com docs and GitHub release downloads.
Well-structured doc (quick report → checks → interpretation → rules) with progressive disclosure and an agent metadata file. Deducted for no skill-level version/changelog, NOASSERTION license metadata, no documented maintenance notes for the bundled script, and troubleshooting left to the main README rather than an in-skill FAQ.
Core task (read-only diagnostics plus interpretation rules producing a support-safe summary) is plausibly completed with marginal value over manual troubleshooting. Deducted because static review cannot verify actual script output format or usability, and the script file's absence makes the core deliverable unverifiable.
Repository contains real CI workflows and tests, but none cover this skill's key paths; claims (read-only script, existence of referenced commands) lack auditable primary material. Deducted for no skill-level tests, reproduction records, or third-party corroboration, and no fact/inference separation.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →