Investigate cmux interface and runtime problems using debug logs, profiling, and the Debug menu. It guides changes to terminal rendering and tab lists, with checks for typing latency, SwiftUI state handling, and differences between macOS versions.
Debug logging, Debug menu, runtime pitfalls, typing-latency-sensitive paths, SwiftUI list snapshot boundaries, OS-version repros, and local visual iteration for cmux. Use when adding debug probes, diagnosing UI/runtime issues, touching terminal rendering, tab/sidebar list views, drag/drop UTTypes, or using the Debug menu.
Review the instructions the agent will receive before you install.
Put debug event instrumentation (keys, mouse, focus, splits, tabs) in the unified DEBUG build log. This is not a requirement to log every new code path; most probes belong to a dogfood debug loop and are removed before merge.
tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"
/tmp/cmux-debug.log; tagged (./scripts/reload.sh --tag <tag>) to /tmp/cmux-debug-<tag>.log.reload.sh writes the current log path to /tmp/cmux-last-debug-log-path and the selected dev CLI path to /tmp/cmux-last-cli-path, and points /tmp/cmux-cli and $HOME/.local/bin/cmux-dev at that CLI.Packages/macOS/CMUXDebugLog/Sources/CMUXDebugLog/DebugEventLog.swift. App shim: Sources/App/DebugLogging.swift. Both are #if DEBUG, so every call site must be wrapped in #if DEBUG / #endif.cmuxDebugLog("message") timestamps and appends in real time. A 500-entry ring buffer backs it; CMUXDebugLog.DebugEventLog.shared.dump() writes the full buffer to file.AppDelegate.swift (monitor, performKeyEquivalent); mouse/UI events inline in views (ContentView, BrowserPanelView).focus.panel, focus.bonsplit, focus.firstResponder, focus.moveFocus, tab.select, tab.close, tab.dragStart, tab.drop, pane.focus, pane.drop, divider.dragStart.Profile a tagged build by attaching to its pid (xctrace record --attach <pid>, sample <pid>). Never use xctrace --launch or Instruments' launch mode on any cmux bundle, and never quit, kill or relaunch the user's running cmux (com.cmuxterm.app): it holds their live agent sessions, and on 2026-09-26 a suspected profiler relaunch took five of them down.
DEBUG builds get a Debug menu in the macOS menu bar. When the user says "debug menu" or "debug window" they mean this, not defaults write.
Debug > Debug Windows holds panels for tuning layout, colors, and behavior, listed alphabetically with no dividers. To add one: create an NSWindowController subclass with a shared singleton, register it in the "Debug Windows" menu in Sources/cmuxApp.swift, and back it with a SwiftUI view using @AppStorage bindings for live changes.
Resources/Info.plist under UTExportedTypeDeclarations.ghostty_surface_draw loop; rely on Ghostty wakeups/renderer to avoid typing lag.WindowTerminalHostView.hitTest() in Sources/TerminalWindowPortal.swift runs on every event including keyboard. Add no work outside the allowsPortalPointerHitTesting guard in performHitTest.TabItemView in Sources/ContentView.swift uses Equatable plus .equatable() to skip body re-evaluation during typing. Do not add environment/store/binding reads without updating == and keeping .equatable() at the call site.TerminalSurface.forceRefresh() in Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+ForceRefresh.swift runs on every keystroke. No allocations, file I/O, or formatting.SurfaceSearchOverlay must be mounted from GhosttySurfaceScrollView in Sources/GhosttyTerminalView.swift, not from SwiftUI panel containers.LazyVStack / LazyHStack / List / ForEach boundary receive immutable snapshots plus closures, never an observable store.body must not mutate state or schedule store writes.No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Organize cmux windows, workspaces, and split panes so an agent can target the right terminal reliably. Create terminals with startup commands, move or reorder panels, change focus, and flash a panel to identify it.
Guide substantial Swift changes in cmux with rules for package boundaries, dependency direction, state management, concurrency, and API documentation. Structure code so public package types can be tested without launching the app.
Guide cmux backend changes with consistent rules for Effect, a TypeScript library for structured error handling. Covers Cloud VM state, database migrations, provider integrations, and authentication and payment checks so changes follow the intended architecture.
Maintain cmux billing code with guidance on Stripe checkout, pricing, subscriptions, and access rights. It maps the relevant services and provides workflows for testing purchases, handling payment events, and rolling out billing changes.
Automate browsing in cmux panels without taking focus away from current work. Target a specific panel to open pages, fill forms, click controls, wait for page changes, extract content, and inspect download history.
Capture cmux windows as screenshots or video clips from the CLI. Create visual evidence for pull requests and bug reports, with region selection and captions to explain drags, animations, or layout changes.