Troubleshooting
Start from what you see, then follow the linked guide. If none of them matches, ask in Discord or open an issue on GitHub. Report security problems privately as described in SECURITY.md.
Agents and sessions
| Symptom | Guide |
|---|---|
| An agent shows “working” but nothing moves | When an agent looks stuck |
| A pane shows a “Shell exited” overlay | What Shell Exited means and how to recover |
| A session is wedged and does not respond | Debugging stuck daemon sessions |
| More than one daemon process is running | Multiple daemon processes |
| Sessions after closing the window, a crash, or a reload | Why closing the window does not kill your agents |
| Sessions after the laptop slept | Terminal sessions across sleep and suspend |
| Output has a gap marker after reconnecting | Understanding ReplayGaps |
| Inline images disappear from scrollback | When inline images truncate in scrollback |
Worktrees and parallel agents
| Symptom | Guide |
|---|---|
.git/index.lock errors with several agents | Why parallel agents fight over index.lock |
| Dev servers collide on the same port | Why parallel agents fight over ports |
| Agents overwrite each other’s database or migrations | Parallel agents and database collisions |
| A worktree is on a detached HEAD | Detached HEAD states and agent worktrees |
Layout and workspace
| Symptom | Guide |
|---|---|
| Panes restore into the wrong tree | Recovering a corrupted workspace layout |
| The layout did not come back after a restart | Restoring your workspace layout |
Remote access and pairing
| Symptom | Guide |
|---|---|
| Sign-in link not arriving, device will not connect, relay unreachable | Remote pairing troubleshooting checklist |
| Typing on a remote session feels slow | Understanding remote terminal input latency |
| Remote sessions after the VPN dropped | Remote terminals when the VPN drops |
| An SSH session froze | Recovering an unresponsive SSH session |
| Agents died when SSH disconnected | Keep agent sessions alive after an SSH drop |
| Korean (Hangul) input misbehaves on the mobile client | Fixing Korean IME input in remote terminals |
Input, rendering, and platform
| Symptom | Guide |
|---|---|
| Paste does nothing or pastes the wrong thing | Clipboard and paste failures across platforms |
| Stale or ghosted grid after a monitor change | Terminal resize ghosting after monitor changes |
| Blurry text under Wayland fractional scaling | Fixing blurry output under Wayland scaling |
| Agent TUIs misbehave on Windows | Windows ConPTY quirks with agent TUIs |
| Notifications or the Dock badge never appear | Notifications and Dock badge not appearing |
Install
| Platform | Guide |
|---|---|
| macOS | Install Ferryx on macOS |
| Windows | Install Ferryx on Windows |
| Linux | Install Ferryx on Linux |
| Headless Linux host | Headless Linux host setup |