Troubleshooting

Quick Triage

1. 1. Confirm dependencies: yabai, iTerm2, and Chrome are installed and running.
2. 2. Confirm accessibility permissions are granted.
3. 3. Confirm workspace is not archived and has valid settings.
4. 4. If launch reports existing runtime state, run mx workspace up --restart (or restart) instead of launch.
5. 5. Re-open workspace detail to refresh live browser-tab and window state.

Workspace Creation Failures

• • `Branch name is required for git projects`: provide `--branch` when creating the workspace.
• • `Target branch not found`: use a valid local or remote target branch.
• • Workspace name conflict: use a unique workspace name or archive/delete old workspace state.
• • Project directory errors: confirm the project path exists and is accessible.

Launch/Restart/Stop Issues

• • `Workspace is already running. Use restart.`: call restart to reconcile stale runtime state.
• • No terminals open: verify iTerm2 is installed and available.
• • No browser sessions open: verify Chrome is installed and session URLs are configured.
• • Services remain after stop: move extra teardown into workspace `stop_script`.

mx workspace up --dir /path/to/workspace
mx workspace restart --dir /path/to/workspace
mx workspace stop --dir /path/to/workspace
mx workspace launch --dir /path/to/workspace

Window and Browser Routing Issues

• • Missing window shortcut targets: open the workspace and recapture windows via launch/restart.
• • Browser tab not focused correctly: confirm browser sessions use stable URL prefixes.
• • Shared Chrome window confusion: keep workspace session URLs distinct where possible.
• • Stale state after app restart: select workspace and trigger refresh/restart flow.

Status Check Issues

• • Red checks: run the check command manually inside workspace context.
• • Timeout failures: increase timeout if service startup is slower than expected.
• • No checks shown: confirm the check `process` field matches a process template name.
• • Unexpected output: verify check command handles auth headers and local routing.

Keyboard Shortcut Issues

• • Global toggle shortcut does nothing: rebind in Settings if another app intercepts it.
• • `cmd+1..9` does not focus windows: ensure workspace has tracked windows in the Run tab list.
• • Next/previous cycles wrong context: focus the intended workspace first (`cmd+shift+return`).
• • Text input edits blocked: verify focus is inside a text field before using edit shortcuts.