Troubleshooting

Windows says “Windows protected your PC” when I run the installer

The installer isn’t code-signed yet, so SmartScreen warns about it. Click More info, check that the app is NeuroSquad-Installer.exe, then Run anyway. Only download the installer from our download page . See Install.

The web installer says it couldn’t download NeuroSquad

NeuroSquad-Installer.exe needs to reach github.com, where NeuroSquad is published. Check the connection or the proxy and press Try again. If GitHub is limiting requests from your network, wait a few minutes — or download the full installer directly: https://neurosquad.ai/downloads/NeuroSquad-Setup.exe. The web installer never runs a file whose SHA-256 checksum doesn’t match. Its log is in %TEMP%\NeuroSquad-Installer-<date>.log.

The installer failed or says NeuroSquad is still running

Close NeuroSquad (including from the tray), or let the installer end its processes with End them and continue. For anything else, the failure page explains what went wrong; the full log is in %TEMP%\NeuroSquad-Setup-<date>.log (and in install.log in the install folder). A failed update leaves the previous version working. See If something goes wrong.

An agent I installed shows as “Not found”

Open Settings → Harnesses and press Check again. Still missing? Quit NeuroSquad completely (including from the tray) and start it again, or install the agent through Settings → Setup.

The agent card closes straight away

Try running the same agent in your own terminal, in the same folder. The message it shows there is usually the answer — most often it isn’t signed in yet.

I drew an arrow, but the agent says it has no tools

Check the agent is Claude Code, Codex CLI or Qwen Code.
For agent-to-agent arrows, check the direction: from the lead to the helper.
Ask the agent to “check your NeuroSquad connections”.

The agent ran a command in its own window instead of my terminal card

Say it in your prompt: “run every command in the connected terminal”. Or turn on canvas mode.

A browser card won’t start

The first time, it needs to download a browser. If the download was interrupted, go to Settings → Browser and press Resume download.

Dictation does nothing

The speech model may not be downloaded yet — the status bar then says Dictation: download the model. Download it in Settings → Dictation.
Another app may be using the same hotkey — change it in Settings → Dictation.
Check that Windows lets desktop apps use the microphone (Windows Settings → Privacy & security → Microphone).
If the text went to the clipboard but not into the agent, NeuroSquad wasn’t the front window — just paste it.

My phone can’t connect

On Local network, the phone must be on the same Wi-Fi. Try picking a different Network address in Settings → Remote access.
On a quick internet tunnel, the address changes each time NeuroSquad starts — scan the code again.

Usage shows nothing

Usage is read from the logs of Claude Code, Codex CLI, OpenCode, Hermes Agent, Pi and omp; other agents aren’t counted. Try a longer period, or press Refresh.

The Telegram card won’t connect

Paste the whole token BotFather sent you, then send /start to your bot and press Allow in the card. Messages from chats you haven’t allowed are ignored.

No key is saved — the agent’s model chip turns amber. Add the key in Settings → Providers, then restart the agent.

Everything feels slow with lots of cards

Each agent card is a running program. Close the ones you no longer need, and zoom out — cards turn into light overview tiles.

Still stuck?

Ask in the NeuroSquad Discord. Say what you did, what you expected and what happened instead; a screenshot helps.

”… isn’t installed” on an agent card

The card’s agent CLI isn’t on this computer (or not on its PATH) — for example a helper a lead agent created with an agent you don’t have. The card offers Install… (the setup wizard), Pick another harness (switches this card to one you have installed, keeping its place and arrows) and Try again (after you installed it yourself — no restart needed).