Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

cmux-debugging

/cmux-debugging

Wspiera debugowanie cmux: logi debug, menu Debug, pułapki środowiska uruchomieniowego, ścieżki wrażliwe na opóźnienia pisania, granice snapshotów list SwiftUI, repro dla wersji systemu i lokalne iteracje wizualne.

Repozytorium
cmux ↗
Licencja
GPL-3.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

GPL-3.0, otwarta.

Co robi i kiedy

Wspiera debugowanie cmux: logi debug, menu Debug, pułapki środowiska uruchomieniowego, ścieżki wrażliwe na opóźnienia pisania, granice snapshotów list SwiftUI, repro dla wersji systemu i lokalne iteracje wizualne.

Oryginalny opis (EN)

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.

Jak działa

  1. Debug event log
  2. Profiling
  3. Debug menu
  4. Runtime pitfalls
  5. Detailed references
Sekcje z nagłówków SKILL.md, w oryginale · 45 linii, 505 słów
Podgląd SKILL.md
---
name: cmux-debugging
description: "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."
---

# cmux Debugging

## Debug event log

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.

```bash
tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"
```

- Untagged Debug app logs to `/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.
- Implementation: `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.
- Key events are logged in `AppDelegate.swift` (monitor, `performKeyEquivalent`); mouse/UI events inline in views (`ContentView`, `BrowserPanelView`).
- Stable event prefixes: `focus.panel`, `focus.bonsplit`, `focus.firstResponder`, `focus.moveFocus`, `tab.select`, `tab.close`, `tab.dragStart`, `tab.drop`, `pane.focus`, `pane.drop`, `divider.dragStart`.

## Profiling

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 menu

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.

## Runtime pitfalls

- Custom drag-and-drop UTTypes must be declared in `Resources/Info.plist` under `UTExportedTypeDeclarations`.
- Do not add an app-level display link or manual `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.
- Views below a `LazyVStack` / `LazyHStack` / `List` / `ForEach` boundary receive immutable snapshots plus closures, never an observable store.
- Functions called from SwiftUI `body` must not mutate state or schedule store writes.
- Foundation, SwiftUI, AttributeGraph, and WebKit semantics change between macOS majors. Test on the reporter's macOS before declaring a user repro disproven.

## Detailed references

- [references/debug-event-log.md](references/debug-event-log.md): when to add probes and how to name them.
- [references/runtime-pitfalls.md](references/runtime-pitfalls.md): read before touching terminal rendering, hit testing, tab rows, list virtualization, search overlay layering, or OS-version-sensitive code.
Pliki w paczce (4)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • references/debug-event-log.md 1 KB
  • references/runtime-pitfalls.md 4 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · manaflow-ai/cmux100GPL-3.0
legotec73/CMUX100GPL-3.0

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 579305e29e94 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100cmux-custom-sidebar
    Buduje własny pasek boczny cmux z opisu w zwykłym języku: plik w stylu SwiftUI w ~/.config/cmux/sidebars/, flaga beta, wybór paska i iteracje z hot reload.
  • 100cmux-sidebar-builder
    Buduje, sprawdza i poprawia własne widoki paska bocznego cmux za pomocą interpretera w stylu SwiftUI, w tym pliki ~/.config/cmux/sidebars/*.swift i podglądy w selektorze paska.
  • 85cmux-shared-behavior
    Opisuje wspólne reguły zachowania w cmux, gdy jedna funkcja działa jednocześnie przez skróty, menu, CLI, ustawienia i optymistyczny interfejs.
  • 90cmux-testing
    Dobiera zakres testów cmux, dodaje testy zachowania i sprawdza cele testowe Swift w konfiguracji.
  • 90cmux-testing
    Dobiera zakresową weryfikację cmux, pisze testy zachowania i sprawdza cele testów Swift oraz ich podpięcie w projekcie.
  • 90cmux-testing
    Dobiera zakresową weryfikację cmux, pisze testy zachowania i sprawdza cele testów Swift oraz ich podpięcie w projekcie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.