# Troubleshooting and uninstall

> Fix common nsq problems — nsq doctor, the terminal addon (node-pty, ConPTY), hooks that need curl, the keyring — and remove nsq cleanly.

Source: https://docs.neurosquad.ai/en/cli/troubleshooting

## Start with `nsq doctor`

```sh
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](https://docs.neurosquad.ai/en/cli/configuration).

## No notifications

See [Notifications](https://docs.neurosquad.ai/en/cli/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

```sh
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.