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.

A Session Seems Stuck "Generating" Forever

If a CLI session has shown "generating" for far longer than the task should take, first check the No Progress Alert setting on that agent (dashboard gear button) — it fires a notification once a turn runs past its threshold, which is often the first real signal something is wrong rather than just a long turn. If the terminal itself looks frozen or garbled (most often seen with Antigravity CLI after certain tool output), reopen the session — ADHDev will nudge a redraw and re-check the real status. If it is still stuck after that, use the session-host recovery path above rather than force-closing and relaunching a duplicate.

CLI Provider Is Not Launchable

If the launcher says there are no usable CLI 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.

A CLI Session Looks Idle But Never Responds

If a CLI session sits there answering instantly with nothing, or looks otherwise idle without actually being usable, check whether the underlying tool's login has expired — a common cause is an expired login/session/credential that the CLI itself reported ("Login expired", "session has expired", etc.). ADHDev detects this per-session and marks the session errored instead of leaving it looking like a healthy idle worker. Re-authenticate the tool itself (its own login command), then relaunch or reconnect the session.

Repo Mesh Skips A Provider During Dispatch

If a Repo Mesh task is never claimed by a node you expected to pick it up, check whether that node's provider is currently reporting quota/usage-limit exhaustion (adhdev quota <provider>). The mesh queue deliberately will not dispatch new work to a provider it has a fresh reading of as exhausted, and routes to another idle node instead. Once quota resets (or you run adhdev quota refresh <provider>), the node becomes eligible again.

Windows Console Window Flashes During Update (partially fixed in 1.0.60)

On Windows a console window can flash briefly while adhdev update runs and right after the daemon restarts on the new version. 1.0.60 removes the flashes from the update pipeline itself (the npm install, the atomic install swap, and the health-check polling), and also fixes the per-installed-CLI-provider flash that used to appear right after the upgraded daemon starts (it probes each CLI's --version). One flash is still known and being worked on: a node.exe window when a session is stopped, coming from a third-party library call with no window-hiding option of its own. It is cosmetic — the session stop still completes normally. If you see a flash at any other moment, please report it with the window title.

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