Skip to main content
This guide covers common issues you might encounter while using cmux and how to resolve them.

​
Installation issues

​
App won’t open on first launch

On first launch, macOS may ask you to confirm opening an app from an identified developer. Solution: Click Open when prompted. This is a standard macOS security measure for apps downloaded outside the App Store.

​
Homebrew installation fails

If brew install --cask cmux fails, the tap might not be properly added. Solution: Ensure you’ve added the tap first: 
brew tap manaflow-ai/cmux
brew install --cask cmux

​
Configuration issues

​
Themes and colors not loading

cmux reads your Ghostty configuration from ~/.config/ghostty/config. Solution: Verify your Ghostty config file exists and contains valid configuration. Create the directory if needed: 
mkdir -p ~/.config/ghostty
Reload the configuration with Cmd+Shift+, after making changes.

​
Custom fonts not appearing

Solution: Ensure the font is installed system-wide and properly configured in your ~/.config/ghostty/config: 
font-family = "Your Font Name"
Reload configuration with Cmd+Shift+,.

​
Notification issues

​
Notifications not appearing

If terminal notifications aren’t showing blue rings or lighting up tabs, the notification system might not be receiving signals. Solution: Verify you’re sending notifications using the correct method: 
cmux notify "Your message here"
Or use OSC sequences (OSC 9/99/777) directly from your agent hooks.

​
Blue notification rings stuck

Solution: Jump to the notification with Cmd+Shift+U to clear it, or click directly on the pane with the blue ring.

​
Browser issues

​
Browser won’t load localhost URLs

If the in-app browser fails to load localhost or 127.0.0.1 URLs: Solution: Check the HTTP host allowlist in Settings. You may need to add localhost to the allowlist or click “Proceed” when prompted.

​
Browser developer tools not working

Solution: Toggle Developer Tools with Opt+Cmd+I (Safari default). If this doesn’t work, check your keyboard shortcuts in Settings.

​
Performance issues

​
Terminal feels laggy

Solution:
  • Check if you have many split panes open. Consider closing unused splits.
  • Verify GPU acceleration is working by checking Activity Monitor for GPU usage.
  • Reload the configuration with Cmd+Shift+,.

​
High CPU usage

Solution:
  • Check for notification loops or excessive logging.
  • Restart the app to clear any stuck processes.
  • Check Activity Monitor to identify which process is consuming CPU.

​
Session restore issues

​
Active processes not resuming after restart

cmux currently restores app layout and metadata only (window/workspace/pane layout, working directories, terminal scrollback, browser URLs). It does not restore live process state inside terminal apps yet.
Active Claude Code, tmux, or vim sessions won’t automatically resume after restart. Solution: Use tmux or similar session managers to preserve your terminal sessions across cmux restarts.

​
Update issues

​
Auto-update not working

Solution:
  • Check for updates manually via the cmux menu.
  • If using Homebrew, update with: brew upgrade --cask cmux
  • For DMG installations, cmux uses Sparkle for auto-updates. Check Settings for update preferences.

​
Nightly builds not appearing

Solution: Enable nightly updates in Settings under “Receive Nightly Builds”. Note that nightly builds are a separate app that runs alongside the stable version.

​
CLI and scripting issues

​
Socket commands not working

Solution: Verify the socket exists: 
ls -la /tmp/cmux.sock
If it doesn’t exist, cmux might not be running or the socket path might be different for debug builds (/tmp/cmux-debug.sock).

​
Commands target wrong workspace

By default, CLI commands use the CMUX_WORKSPACE_ID environment variable. Solution: Use explicit targeting flags: 
cmux send --workspace <id> "your command"

​
Getting help

If you’re still experiencing issues:
  • Check the GitHub issues for similar problems
  • Join the Discord community for help
  • Create a new issue with details about your environment and the problem
When reporting issues, include your macOS version, cmux version (cmux --version), and relevant configuration from ~/.config/ghostty/config.