What does this skill do, and when should you use it?
This is one of 25 skills bundled in the manaflow-ai/cmux monorepo, located at skills/cmux-debugging/SKILL.md. It teaches an agent how to add debug event probes to cmux's macOS app, follow the unified DEBUG-build log, use the Debug menu, and respect hard-won runtime rules such as no allocations in forceRefresh and preserving Equatable view optimizations. It also encodes a strict safety rule: never launch cmux under xctrace or Instruments, because the running app holds the user's live agent sessions — an incident on 2026-09-26 took five of them down. It is written for contributors working on cmux itself.
- Explains the unified debug log: tail -f /tmp/cmux-debug.log or the tagged log path stored by reload.sh
- Specifies where to place cmuxDebugLog probes, the #if DEBUG wrapping requirement, and stable event prefixes (tab.select, pane.focus, etc.)
- Enforces safe profiling: attach to the existing pid (xctrace record --attach / sample), never launch mode
- Lists runtime pitfalls: UTExportedTypeDeclarations for drag/drop UTTypes, hot hitTest paths, LazyVStack snapshot boundaries, .equatable() optimization
- Documents how to add a Debug-window panel (NSWindowController subclass with @AppStorage-backed SwiftUI view)
- Links two deep references: references/debug-event-log.md and references/runtime-pitfalls.md
- A cmux contributor adding debug probes to key/mouse/focus event code who needs the correct prefix naming
- A developer about to touch terminal rendering, TabItemView, or TerminalSurface who must check typing-latency-sensitive-path rules first
- Someone diagnosing an OS-version-specific UI repro who must test on the reporter's macOS before dismissing it
- A contributor adding a new layout/color tuning panel to the Debug menu following the existing NSWindowController pattern
- Anyone adding custom drag-and-drop UTTypes who must declare them in Info.plist's UTExportedTypeDeclarations
- Not for developers building their own terminal apps — every rule binds to cmux's specific source paths and internal conventions
- Not for ordinary cmux users who only want to use the terminal; the DEBUG-build debugging machinery is irrelevant to them
- macOS only (cmux itself supports no other platform), so it cannot help on other OSes
How do you install this skill?
- The skill applies only to developing/debugging the cmux repository itself on macOS; it is not a general-purpose skill for cmux users. Gate invocation on the 'cmux' trigger term.
- No version or changelog: rules may drift from the code; verify cited source paths still exist before relying on them.
- Debug-log and profiling guidance touches live user sessions (the doc records an incident losing five agent sessions); always confirm attach mode, never launch/kill/relaunch.
- Repository license metadata is NOASSERTION; the actual LICENSE is GPL-3.0-or-later with BUSL-1.1 directories (web/ etc.), so redistribution requires license review.
- No Chinese documentation; this is a static review — no commands were executed, so reliability rests on source consistency, not runtime verification.
- Shell / CLI
- Local filesystem
macOScmux source treexctrace/sample profilers
The source does not document an install command for this skill. It ships inside the cmux monorepo at skills/cmux-debugging/; obtaining the repo is the only route given. The README only covers installing the cmux app itself (DMG or Homebrew), not skills installation.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/manaflow-ai/cmux.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/cmux-debugging" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I'm adding debug probes to cmux tab drag-and-drop — place the cmuxDebugLog calls in the right spots with the standard event prefixes
- cmux stutters while typing; check my changes to TerminalSurface.forceRefresh and TabItemView against the runtime pitfalls list
- Add a new Debug-menu window for tuning sidebar colors in cmux
- A user-reported bug doesn't reproduce on my macOS — what does the skill say I should do?
The skill triggers via its description: use it when adding debug probes, diagnosing UI/runtime issues, touching terminal rendering, tab/sidebar list views, drag/drop UTTypes, or using the Debug menu. The flow is: instrument probes per convention into the unified DEBUG log, follow with tail, and profile by attaching to a running process instead of relaunching. Core commands:
tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"
xctrace record --attach <pid>
sample <pid>Consult references/debug-event-log.md and references/runtime-pitfalls.md for depth.
What are this skill's strengths and limitations?
- Encodes real, painful lessons from the cmux project, including an incident where a suspected profiler relaunch killed five live agent sessions
- Provides a stable event-prefix naming scheme and ready-to-paste log-tracking commands
- Two deep reference files cover probe naming and runtime pitfalls for quick pre-change review
- Tightly bound to cmux's source layout and internal paths (Sources/ContentView.swift, the CMUXDebugLog package); near-zero value outside this repo
- License field is NOASSERTION on the metadata (app core is GPL-3.0-or-later, server code is BUSL-1.1) — verify commercial boundaries yourself
- No automation scripts accompany the skill; compliance with hot-path rules depends entirely on the model reading and obeying the prose
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 Debugging Skill this page | 56 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Ghostty Submodule Workflow Skill | 54 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Custom Sidebar | 50 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Customization | 55 · Use with care | ★ 28k | 1d ago | NOASSERTION |
The source compares cmux with tmux (tmux is a multiplexer inside any terminal; cmux is a native macOS GUI app), but this skill itself is an internal cmux debugging convention with no directly comparable alternative skill documented.
How did FollowSkills review this skill?
Content is advisory: no network access, no credential handling, no external side effects. The only externally consequential instruction (profiling) explicitly forbids killing/relaunching the user's running cmux, citing a real incident, and restricts to attach mode — least-privilege oriented. The tail command reads local /tmp files only. Deductions: unverified publisher (not itself penalized per rules), one-sided claims about reload.sh behavior and /tmp path writes without independent confirmation, and no discussion of sensitive data that debug logs may contain.
High internal self-consistency: SKILL.md and both references align on paths, event prefixes, filenames; concrete implementation locations, ring buffer/dump mechanism, and explained failure modes (unguarded #if DEBUG breaking non-Debug builds). Deductions: static review only — the tail command and script behaviors were not executed; behavior when the /tmp state files are absent is not specified; no test evidence for the skill itself, so the static cap of 10 applies.
Precise trigger semantics: clear use cases (debug probes, UI/runtime diagnosis, rendering, UTTypes, Debug menu) and disambiguation of 'debug menu'; clear boundaries (macOS only, DEBUG builds only, cmux repo contributors). Deductions: no Chinese-language support; audience limited to this repository's developers; no explicit non-fit/environment declarations inside the skill.
Good layered structure: concise SKILL.md with progressive disclosure into references, stable naming, specific issue citations. Deductions: no skill version, changelog, or maintenance statement; repository license metadata is NOASSERTION (actual LICENSE is GPL-3.0-or-later plus BUSL-1.1 directories, but the skill does not state its own licensing); install/dependency prerequisites are assumed rather than documented.
If the scenario matches (debugging inside the cmux repo), the skill delivers hard-won pitfall rules (hitTest hot paths, equatable boundaries, OS-version differences) with clear marginal value. Deductions: value is confined to one repository; static review cannot verify outputs are directly usable; near-zero utility for non-maintainers limits cost/benefit.
Many auditable claims: implementation file paths, event prefixes, Info.plist UTType names, issue links #2586/#4529/#14427, all cross-checkable against repository sources. Deductions: nothing executed or independently reproduced; the cited issue contents are not confirmable from the supplied evidence; claims and inferences are not strictly separated; static cap of 5 applies.
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 →