Troubleshooting

Common issues and how to fix them.

IDE not appearing in dashboard

Symptoms: Dashboard shows "No IDE connected" even though your IDE is open.

Solutions:

1. Launch with CDP: Your IDE needs Chrome DevTools Protocol enabled.

   adhdev launch cursor

2. Check daemon is running:

   adhdev status

3. Verify connection: Check the daemon logs for connection errors.
4. Firewall: Ensure ports 9333-9340 (CDP) aren't blocked.

Remote view not working

Symptoms: Remote view shows black screen or "CDP not connected" warning.

Solutions:

1. Relaunch with CDP:

   adhdev launch cursor

2. Check P2P status: Look for the green dot (🟢) on the tab — if yellow (🟡), P2P is reconnecting.
3. Network issues: P2P requires WebRTC. Some corporate firewalls block this.

"Reconnecting..." stuck on mobile

Symptoms: After switching to another app and coming back, the dashboard shows "Reconnecting..." indefinitely.

Solutions:

1. Pull to refresh the page
2. Close and reopen the browser tab
3. This is a known issue with mobile browser WebSocket hibernation — we're improving reconnection logic

Chat is empty / "Loading chat..."

Symptoms: Tab shows green status but no messages appear.

Solutions:

1. Wait a few seconds — P2P data may still be loading
2. Click the tab to trigger data refresh
3. Check IDE: Make sure the AI agent panel is visible in your IDE (not collapsed/hidden)

CLI agent won't launch

Symptoms: adhdev launch gemini fails or agent doesn't appear in dashboard.

Solutions:

1. Check installation: Verify the CLI tool is installed

   gemini --version    # Gemini CLI
   claude --version    # Claude Code
   codex --version     # Codex CLI

2. Check API keys: Each CLI agent needs its own API key configured
3. Check daemon logs: Look for error messages in daemon output

P2P connection keeps failing

Symptoms: Connection status stays yellow or cycles between connecting and failed.

Solutions:

1. Network: P2P works best on networks that allow UDP traffic
2. VPN: Some VPNs block WebRTC. Try disconnecting VPN
3. Symmetric NAT: Some networks have symmetric NAT which prevents direct P2P. TURN relay (Pro+) can help

Dashboard is slow

Solutions:

1. Close unused tabs: If you have many agents, hide tabs you don't need
2. Disable Remote View: Screenshots consume bandwidth — only open when needed
3. Check P2P transport: In settings, check if you're on TURN relay (slower) or direct STUN (faster)

Getting Help

• GitHub Issues: github.com/vilmire/adhdev/issues
• Dashboard Logs: Check browser console for error messages (F12 → Console)
• Daemon Logs: Run adhdev status or check ~/.adhdev/logs/