Troubleshooting

The CLI cannot reach the app

Most failures are socket failures. Check reachability first.

cmux ping
cmux identify --json
cmux capabilities
echo "$CMUX_SOCKET_PATH"
ls -l ~/.local/state/cmux/cmux.sock

automation.socketControlMode defaults to cmuxOnly, which is why a script run from another terminal app is refused. Use password with a password, or allowAll if you accept any local process driving cmux. --socket <path> overrides for one call.

Config edits do nothing

cmux settings path
cmux config validate
cmux config doctor
cmux reload-config

reload-config reloads cmux.json and ~/.config/ghostty/config and refreshes terminals in place, so a restart is almost never the fix.

Common causes, in order:

1. Editing the wrong file. Terminal font, theme, colors, cursor, opacity, blur, and scrollback are Ghostty settings. Sidebar, notifications, browser, and app behavior are cmux settings. 2. Editing a legacy file. ~/.config/cmux/settings.json and ~/Library/Application Support/com.cmuxterm.app/settings.json are read only for keys missing from cmux.json. 3. Invalid JSON. A trailing comma silently loses the whole file, which is what config validate catches. 4. An unknown key. Point $schema at the published schema and let your editor flag it.

Shortcuts not firing

1. Ask who owns the key. Terminal keys come from Ghostty config, everything else from cmux Settings > Keyboard Shortcuts. 2. Check for a when clause on the action. A predicate that does not hold makes the shortcut inert, and it also stops it conflicting with others. 3. Check the first stroke has a modifier. Only Space is allowed bare, plus a few actions that opt into bare first strokes. 4. Some actions ship unbound on purpose: mark all notifications read, clear all notifications, reopen closed workspace, focus previous and next pane. 5. cmux reload-config after editing, then confirm with the hint chips by holding ⌘.

Notifications not arriving

cmux notify --title test --body "does this show"
cmux list-notifications

If a manual cmux notify works but your agent produces nothing, the gap is the hook layer, not cmux.

- Install the agent CLI first, then cmux hooks setup, so the binary is on PATH when hooks are written. - Check the per-agent integration switch in automation, for example claudeCodeIntegration. - notifications.agentTurnComplete defaults to whenIdle, which deliberately holds the ping while the agent still has a background task or a scheduled wakeup. Set always to see every turn end. - suppressSubagentNotifications defaults to true, so nested subagent completions stay quiet. - Rings and badges have their own switches: unreadPaneRing, dockBadge, showInMenuBar.

Terminals look wrong or feel slow

Rendering is libghostty, so the fixes are Ghostty's.

- Put font, theme, and background-opacity in ~/.config/ghostty/config, then cmux reload-config. - terminal.adaptiveDefaultTheme supplies cmux's managed light and dark palette only when your Ghostty config does not set one, so an unexpected palette usually means one side is not set. - app.globalFontMagnification scales cmux chrome and terminals together, separate from Ghostty's font-size. - Check surface health and resource use before blaming the renderer:

cmux surface-health
cmux top --processes --sort mem
cmux memory --all
cmux debug-terminals

terminal.rendererRealization releases the Metal renderer for off-screen terminals, and terminal.agentHibernation kills idle off-screen agents and resumes them when you visit the tab. Under critical memory pressure cmux may hibernate a bounded batch of safe idle background agents even when hibernation is disabled.

Sessions did not come back

cmux restores window, workspace, and pane layout, working directories, best-effort scrollback, and browser URLs and history. It does not checkpoint arbitrary live processes, so plain shells, vim, and unsupported apps reopen as ordinary terminals.

cmux restore-session          # reapply the last saved snapshot
cmux hooks setup              # required for agent session resume

Agent sessions resume only when hooks saved a native session ID. To stop restored agent terminals from auto-running their resume command, turn off Settings > Terminal > Resume Agent Sessions on Reopen, or set it in cmux.json:

{ "terminal": { "autoResumeAgentSessions": false } }

Snapshots live under ~/Library/Application Support/cmux/ and hook session mappings under ~/.cmuxterm/. ⌘⇧O and File > Reopen Previous Session do the same thing as cmux restore-session.

Getting the facts before reporting a bug

cmux version
cmux capabilities
cmux config doctor
cmux tree --all

The CLI moves fast, so cmux --help and cmux <command> --help for your installed build outrank any external reference. Issues go to github.com/manaflow-ai/cmux/issues, and cmux feedback --email you@example.com --body "..." files one from the shell.