Skip to Content
Terminal CLI (nsq)Troubleshooting and uninstall

Troubleshooting and uninstall

Start with nsq doctor

nsq doctor

It prints the nsq and Node versions, the data folder, whether the daemon runs, where each agent CLI was found, whether curl and the terminal addon work, whether an OpenRouter key is available, and your terminal and its size. Paste it into a bug report.

The daemon’s log is ~/.neurosquad-cli/daemon.log.

An agent is “not found”

nsq starts the CLI from your PATH, plus the usual install folders (and, on Windows, the current PATH from the registry, so a CLI installed a minute ago is found). Check that claude, codex or opencode runs in your terminal; nsq doctor shows what nsq found. If a CLI lives somewhere unusual, run nsq down, then start nsq again from a terminal where the CLI works (running agents are resumed).

The status never changes, or “needs you” never comes

Claude Code and Codex report their status through curl. If nsq doctor says curl MISSING, install it (it ships with Windows 10 and later, macOS and most Linux distributions). A plain command (nsq run -- …) never shows “needs you” — it has no hooks.

The terminal addon fails to load (node-pty)

nsq drives terminals with node-pty, prebuilt for every supported platform — nothing is compiled on install. If nsq doctor shows node-pty FAILED:

  • check node --version is 22.13 or newer, and reinstall nsq after changing Node versions (npm install -g neurosquad);
  • make sure install scripts were not disabled for that install (--ignore-scripts);
  • on Windows, nsq uses ConPTY, the Windows pseudo-console (Windows 10 version 1809 or later). Windows Terminal is the best host for the dashboard; the old console window works but draws less.

Garbled characters, wrong colours or broken logos

Your terminal may not support what nsq detected. Try NSQ_GLYPHS=ascii, NSQ_COLOR=256 or NSQ_LOGOS=glyphs (or none), and NSQ_AMBIGUOUS_WIDE=1 if boxes look shifted in a CJK setup. See Configuration.

No notifications

See Notifications: on macOS install terminal-notifier or allow Script Editor to notify; on Linux a notification service must run on the desktop. Over SSH, keep the dashboard open — it rings the terminal.

The OpenRouter key is not kept

The key lives in the OS keyring. On Linux this needs the Secret Service (GNOME Keyring, KWallet), which a server often does not have; set OPENROUTER_API_KEY in the environment the daemon starts from instead.

Uninstall

nsq down                          # stop the daemon and its agents
nsq openrouter clear-key          # remove the OpenRouter key from the keyring
nsq logout                        # only if you signed in
npm uninstall -g neurosquad

Then delete ~/.neurosquad-cli (or your NSQ_HOME) — it holds the agent list, settings, logs, the dictation model and agents’ worktrees, so check worktrees/ for work you want to keep first. Branches nsq created (nsq/<name>) stay in your repositories until you delete them with git. Your agent CLIs and their own settings were never changed.

ConfigurationOverview