Troubleshooting
Most issues come down to a shell that started before install, or notifications not being allowed. Here’s the short list.
My terminal doesn’t appear in the list
The shell hook only applies to new shells. A terminal opened before you installed (or before the agent started) won’t be wrapped.
Fix: open a new terminal window, or run exec zsh in the existing one. It’ll appear in the list within a moment.
Pairing failed or the fingerprints don’t match
If the fingerprints on your Mac and phone don’t match, do not approve — abort and try again. A mismatch is the channel-binding check doing its job.
Fix: generate a fresh QR from the menu-bar popover and re-scan. Make sure both devices have internet access.
The connection dropped when I changed networks
TermBridge reconnects automatically. Both ends use exponential-backoff reconnect, plus an instant reconnect the moment your network flips (cellular ↔ Wi-Fi) or the app returns to the foreground. When it re-attaches, scrollback replays what you missed.
If it stays disconnected, confirm the Mac is awake and online — a sleeping Mac can’t hold the outbound connection.
My Mac keeps going to sleep
A Mac that sleeps drops its outbound connection to the relay, so its shells stop being reachable until it wakes. If you rely on long unattended runs, adjust your Mac’s sleep settings (or keep it plugged in and awake).
I’m not getting agent notifications
- Check notifications are allowed: iOS Settings → Notifications → TermBridge.
- Notifications fire when an agent is waiting on input — a running-but-not-blocked process won’t ping you.
- Make sure the Mac and phone are paired and the Mac is online.
Everything’s broken — how do I reset?
The shell hook fails safe, so your terminal is never truly broken. If you want a clean slate, run the uninstaller, reinstall, and re-pair.
Still stuck?
Email us or ask in our Discord — we’re responsive.
Next
Read the FAQ for quick answers.