Troubleshooting

Use this page when the dashboard looks out of sync with your machine, a session disappears, or a hosted CLI runtime needs recovery.

Nothing Is Showing Up In The Dashboard

If the dashboard says there are no machines or sessions, check the local daemon first:

adhdev daemon:status

Look for:

• a running daemon process
• reachable local IPC
• session-host status if you use CLI agents

If the daemon is not running, start it again or reinstall the background service if you normally run ADHDev that way.

An IDE Or Agent Is Missing

Before relaunching anything, check the dashboard surfaces that now hide less urgent work:

• Hidden tabs
• Activity inbox
• History

If the machine is connected but a specific IDE session is missing, relaunch that IDE through ADHDev so it starts with the expected control surface:

adhdev launch cursor

Use the matching target for your IDE.

Chat Looks Empty Or Stuck Loading

If the session exists but the chat is blank or still loading:

1. Wait a few seconds for the session stream to settle.
2. Reopen the session from the tab strip, inbox, or history.
3. Check whether the original IDE or CLI tool is still running.
4. If it is a CLI runtime, inspect the session host instead of launching a duplicate session immediately.

For CLI-heavy setups, a missing chat often means the runtime survived but the dashboard needs to reattach to it.

CLI Provider Is Not Launchable

If the launcher says there are no usable CLI/ACP providers, or a built-in provider is missing from launch:

1. Open the machine's Providers tab.
2. Enable the provider on that machine.
3. Run Detect and read the detection/verification detail on the provider card.
4. Set custom executable path/args if the upstream binary is installed outside the default PATH.
5. If you changed provider source mode or providerDir, click Apply + Reload before trying a new launch.

Built-in provider inventory is intentionally separate from machine launchability. A provider becomes launchable only after local activation and detection succeed.

CLI Session Is Stuck After A Restart

Hosted CLI runtimes now have a dedicated recovery path.

First inspect session-host state:

adhdev daemon:session-host

Common recovery actions:

adhdev daemon:session-host --session <sessionId> --resume
adhdev daemon:session-host --session <sessionId> --restart
adhdev daemon:session-host --prune-duplicates

You can do the same from the machine's Hosted Runtimes tab in the dashboard.

Use this when:

• a CLI session survived a daemon restart
• a runtime is stuck in an interrupted state
• duplicate hosted runtimes were created for the same session
• a runtime still exists but the dashboard is attached to the wrong copy

Remote View Is Unavailable

If Remote View is blank or shows a CDP warning:

1. Relaunch the IDE through adhdev launch <ide>.
2. Confirm the IDE is one of the Electron-based flows that ADHDev can control well.
3. Check whether your network or browser is interfering with the live connection.

If the rest of the session works but Remote View does not, treat it as an IDE control-surface issue first, not a general dashboard failure.

Notifications Are Not Arriving

Open Notifications in the dashboard and verify:

• global notifications are enabled
• browser notifications are enabled
• push notifications are enabled if you use the hosted cloud path
• provider-level alert settings are not suppressing the event you expect

Push notifications are cloud-only and work best when ADHDev is installed as a PWA on mobile.

Mobile Dashboard Feels Stuck

Mobile browsers are more aggressive about suspending background tabs.

Try:

1. pulling to refresh
2. reopening the active session from the inbox
3. reopening the tab entirely if the connection did not recover

If you only need to check for approvals, the inbox is usually more reliable than waiting on the previous chat view to restore itself.

Still Broken

If the local state looks inconsistent, collect current status first:

adhdev doctor
adhdev daemon:status
adhdev daemon:session-host --json

adhdev doctor now also checks whether the PATH adhdev / adhmux binaries are stale, broken, or missing the newer runtime surface. If runtime commands seem inconsistent with the docs, check doctor output before assuming the session-host/runtime layer is wrong.

Then check:

• daemon logs in ~/.adhdev/logs/
• the machine's Logs tab in the dashboard
• the machine's Hosted Runtimes tab for interrupted runtimes

Last Resort

If the install itself is corrupted, a clean reinstall is still the fallback:

adhdev uninstall -f
npm uninstall -g adhdev
npm install -g adhdev
adhdev setup
adhdev service install

WARNING

This removes local ADHDev data, including auth state, logs, and cached configuration.

Getting Help

• Compatibility & Caveats
• Dashboard
• CLI Agents
• Self-hosted
• GitHub Issues: github.com/vilmire/adhdev/issues