A blank main area does not always mean the project is gone. Often the terminal panel still exists, while the Ghostty surface failed to bind to the window portal after restore, layout, or agent session churn.
Since imux 5.0.34, the app auto-reattaches unhealthy portals and can show a Doctor recovery prompt. This tutorial explains what to do if you still see black.
Prerequisites
- imux 5.0.34 or later recommended
- A workspace that previously had a terminal
Steps
- 01
Wait for automatic recovery
After launch or switching workspaces, wait 1–2 seconds. imux samples portal health and retries reattach up to twice. Watch for the terminal to repaint without clicking.
- 02
Run Doctor recovery if prompted
If a Terminal display is blank card appears, click Run Doctor Recovery. That path rebinds portals; if still unhealthy it opens a fresh terminal in the same project directory.
- 03
Open a new terminal manually
Use New Terminal / ⌘T (or your custom shortcut). Confirm the working directory is still your project (for example
~/codebase), not an empty home shell. - 04
Resume agent CLIs only if needed
If you were running Grok/Claude/Codex with a resume command, start a clean shell first. Only re-run
grok --resume …/ agent resume when you still need that session transcript. - 05
Last resort: restart imux
Quit imux fully and reopen. Session restore should remount workspaces. Avoid deleting session JSON unless support asks — that drops layout state.
Tips
- Zen mode and large chrome toggles can stress portals; 5.0.34+ re-syncs after chrome changes.
- Automation badges can show an agent as running even when the surface is blank — trust the pixels, then recover.
FAQ
Is my project deleted?
Usually no. Files on disk are untouched. You are recovering the terminal view, not reinstalling the project.
Why did Doctor not appear on older builds?
Older builds only diagnosed empty panels / unmounted workspaces. Blank-but-present terminals need 5.0.34+ health checks.
Can agents keep running while the UI is black?
Yes. A shell process may still own a TTY. Recover the surface or open a new terminal before typing more commands.