nsq — NeuroSquad in your terminal

Run several AI coding agents from one terminal.

nsq starts Claude Code, Codex, OpenCode or any command, keeps them running in a background daemon, shows them as live terminals in one dashboard, and tells you when one of them is waiting for you, including the question it is asking. You can answer from the dashboard.

0.1.0 is a preview. Commands, keys and config may still change before 1.0. Please report what breaks.

Requires Node.js 22.13 or newer. No compiler needed: native parts ship prebuilt for Windows (x64, arm64), macOS (Apple silicon, Intel) and Linux (x64, arm64).

npm install -g neurosquad      # then run: nsq
npx neurosquad                 # or try it without installing

More ways (Homebrew, Scoop, install scripts) and uninstalling: docs/guide/getting-started.md. nsq then keeps itself up to date: installed with npm, Homebrew or Scoop, it installs a new release in the background (other installs show the command to run) and switches to it once nothing would be lost — no busy agent, no open dashboard, every agent able to resume its session — or when you press U (updates; nsq config set autoUpdate false turns it off).

cd ~/code/my-app
nsq run claude "fix the flaky checkout test" --worktree   # an agent on its own branch
nsq run codex --name reviewer                             # a second agent
nsq run -- claude --effort high                           # or the CLI's own command line
nsq run -- npm run dev                                    # any command, as an agent
nsq                                                       # the dashboard

In the dashboard, select an agent with the arrows, press Enter to work in it full screen, and Ctrl+] to go back to the grid. When an agent asks a permission question, press y, a or n without opening it. Press q to close the dashboard — the agents keep running.

• Agents that outlive the window. A per-user daemon owns the terminals. Close the dashboard or the terminal — the agents keep working. nsq down stops them; the next nsq up (or just nsq) brings them back on their own sessions — after a reboot too.
• One dashboard. Workspaces and agents in a sidebar, the selected workspace as a grid of live terminals; any agent opens full screen and goes back to the grid.
• Exact status, with the question. Working / needs you / finished comes from each CLI's own hooks, not from guessing at the screen. "Needs you" carries the harness's own text, e.g. Claude wants to run: npm test.
• Quiet while working. Some prompts come from tools that never fire a hook — git asking for a password, an installer's [y/N], sudo, ssh's host key — or a command just hangs. When a working agent's screen has not changed for 5 minutes (quietAfter; a turning spinner does not count), it shows as quiet — check it, with the prompt it seems to show, and calls you like "needs you".
• Answer inline. y / a / n (yes / always / no) on a permission prompt, i to interrupt, s to send a prompt — or S to send it when the current turn ends.
• An approvals log. Every "needs you" question and how it ended, for all agents, in one file: which agent asked, the exact question (tool, command / path / url), the answer, and who gave it from where — the dashboard, nsq answer, the phone (this machine, the Wi-Fi or the internet, and the device), the agent's own terminal, or the CLI itself. nsq log approvals.
• Notifications and sound. A native notification on Windows, macOS and Linux when an agent needs you or finishes — one per agent, withdrawn when it works again. Over SSH or without a desktop, the dashboard rings its own terminal instead (bell + OSC 9).
• A git worktree per agent. --worktree gives the agent its own checkout on branch nsq/<name>, so parallel agents don't trip over each other. nsq diff <agent> shows its uncommitted changes.
• Cost per agent. nsq cost reads tokens from each harness's own logs. A model without a known price shows "no price", never $0.
• Your config stays yours. ~/.claude, ~/.codex and opencode.json are never written: everything nsq needs lives in a per-agent layer (flags, environment, its own folder).
• OpenRouter built in. One key, any model, for Claude Code, Codex and OpenCode.
• Your own model servers. llama.cpp, Ollama, LM Studio, vLLM, SGLang, Unsloth Studio or any OpenAI- / Anthropic-compatible API — tested, then offered to each CLI that can speak to it.
• Voice dictation. Local speech recognition; the text is pasted into the agent, never sent.
• Phone (experimental). Pair a phone with a QR code and answer your agents from it.
• Terminal graphics. CLI logos over kitty / iTerm2 / sixel graphics, light animations that switch off over SSH and on request, ASCII fallbacks.

Supported: Claude Code, Codex, OpenCode (1.x and 2.x), and any command (nsq run -- <command>; it has no hooks, so it shows working / finished, never "needs you"). Agents that support the herdr status protocol (Crush, Kiro CLI, Command Code and others) work in nsq out of the box with nsq run -- <agent>: they report working, needs you and finished themselves, and nsq resumes their session when they report how to (how). Want another CLI? Request it.

The mouse works too: click selects, double-click opens, the wheel scrolls an agent's output back (over a tile or full screen; Shift+PgUp too) and, over the sidebar, moves the selection. Drag over an agent's text to copy it, click a link to open it in your browser: the dashboard holds the mouse, so it does what your terminal would.

nsq                                   the dashboard (starts the daemon)
nsq run <claude|codex|opencode> [prompt]
        [--name n] [--worktree] [--model id] [--provider name|openrouter]
        [--dangerous] [--attach]
nsq run [--name n] -- <command…>      any command
nsq ls [--json]                       agents and their status
nsq attach <agent>                    full-screen terminal (Ctrl+] to detach)
nsq send <agent> "prompt" [--when-done]
nsq answer <agent> yes|always|no      answer a permission prompt
nsq interrupt|stop|start|restart <agent>
nsq rm <agent> [--worktree]           remove (and delete its worktree)
nsq set <agent> [--dangerous on|off] [--model id|none]
        [--provider name|openrouter|none] [--quiet-after min|default]
nsq diff <agent>                      uncommitted changes (git diff HEAD) in its folder
nsq peek <agent> [-n 20]              the last lines of its screen
nsq cost [--since 7d] [--json]        what each agent spent
nsq log approvals [--agent x] [--since 2h] [--json]
                                      every "needs you" question, its answer and who gave it
nsq openrouter set-key|clear-key|models [query]|status
nsq openrouter test <model> [--harness claude|codex|opencode]
nsq provider add <name> --url <base> [--key-stdin|--ask-key]
                                      your own server: llama.cpp, Ollama, LM Studio,
                                      vLLM, SGLang, Unsloth Studio, any compatible API
nsq provider test|models|remove <name> · nsq provider list
nsq phone on [--lan] [--port n]|off|pair|rotate|status
                                      answer agents from a phone
nsq phone on --online [--expire 12h]  … from anywhere, through a Cloudflare tunnel (https)
nsq phone push ntfy [--url] [--token]|off|test|show|status
                                      push "needs you" to the phone
nsq login | logout | whoami           the optional NeuroSquad account
nsq dictation setup|status|test <wav> [--model id]
nsq up | down                         start / stop the daemon (and its agents)
nsq update [--check]                  install the newest release now (or only check)
nsq config [get|set|unset <key> [value]]   settings, e.g. autoUpdate true|notify|false
nsq doctor                            check harnesses, hooks, terminal, updates

Everything you can do in the dashboard you can also script: nsq ls --json, nsq send, nsq answer.

nsq openrouter set-key                 # stored in the OS keyring (or set OPENROUTER_API_KEY)
nsq run claude --provider openrouter --model anthropic/claude-sonnet-4.5
nsq openrouter models qwen             # search the catalogue

The key only ever goes into the agent's environment — never argv, logs or files. Requests carry NeuroSquad's OpenRouter app attribution headers. Without a key, an agent runs on its CLI's own login. m in the dashboard picks a model and switches the agent to OpenRouter (restarted on the same session, the conversation kept); "default" goes back. Details: docs/guide/openrouter.md.

nsq provider add lmstudio --url http://localhost:1234      # tests it: models, which APIs it speaks
nsq run claude --provider lmstudio --model qwen/qwen3-coder-30b
nsq provider models lmstudio

Local (llama.cpp, Ollama, LM Studio, vLLM, SGLang, Unsloth Studio) or remote, OpenAI- or Anthropic-compatible. Claude Code uses the server's Anthropic endpoint, Codex its Responses endpoint (or chat completions through a local gateway), OpenCode either. The key (optional) is asked for without echo and kept in the OS keyring; requests show "no price". Details and a table of servers: docs/guide/providers.md.

nsq phone on --lan     # off by default; without --lan it listens on this machine only
nsq phone pair         # prints the link and a QR code — scan it with the phone (or Q in the dashboard)
nsq phone on --online  # from anywhere: an https link through a Cloudflare quick tunnel
nsq phone push ntfy    # optional: a push via ntfy when an agent needs you

From the phone you can see the agents and their screens, send a prompt, answer a permission prompt and interrupt. A phone cannot start agents, change settings or type arbitrary keys. The link carries the pairing token — treat it like a password; nsq phone rotate signs every phone out. Pushes through ntfy carry only the agent's name and its question, plus, when phone access is on with --lan, a link to the phone page (your local network address, no token); your own topic URL and token are asked for (or piped in), never put on the command line. --online is opt-in every time and prints a warning: anyone with that link and token can control your agents. The address changes on every start (pair again), wrong tokens from the internet lock an address out, and nsq phone off (or nsq phone on without --online) closes it. cloudflared is used from PATH or downloaded once into ~/.neurosquad-cli/bin, sha256-checked.

This part is the newest and most likely to change: docs/guide/phone.md.

Press v in the dashboard (or the global hotkey, Ctrl+Shift+Space / Cmd+Shift+Space by default) and speak: the text is recognised on your machine and pasted into the agent's input. It is never submitted — you press Enter. The speech model (~670 MB, checked by SHA-256) is downloaded once — with nsq dictation setup, or when you first press v. Not available on Windows arm64. docs/guide/dictation.md.

• No account required. Everything works without signing in.
• No telemetry. nsq does not report usage anywhere.
• Data lives in ~/.neurosquad-cli (move it with NSQ_HOME). Secrets (the OpenRouter key, the ntfy topic and token, the optional account session) live in the OS keyring.
• Network access is what you ask for: your agents' own traffic, OpenRouter if you use it, the one-time dictation model download, ntfy if you turn it on, and the NeuroSquad account if you sign in. Plus the update check: every 6 hours one request to the npm registry for nsq's public package metadata, with nothing about you in it (NSQ_NO_UPDATE=1 or nsq config set autoUpdate false turns it off — updates).
• The approvals log (logs/approvals.jsonl) keeps the questions and answers on your machine only: no environment, tokens or prompts, secret-looking parts of commands masked (nsq config set approvalsLog false turns it off — agents).

Windows 10/11 (x64, arm64), macOS (Apple silicon, Intel), Linux (x64, arm64), each checked in CI from the packed npm package on Node 22 and 24. Works over SSH: the daemon runs wherever you run nsq, and notifications fall back to the terminal.

Getting started · Dashboard and keys · Agents and harnesses · OpenRouter · Worktrees · Notifications · Phone · Dictation · Configuration · Updates · Troubleshooting · Uninstall

How it works inside: harness integrations, agent status.

nsq is the open-source, terminal sibling of NeuroSquad, a desktop app where agents are cards with live terminals on a canvas: 20+ CLIs, agents that talk to each other by arrows, browser/notes/plugin cards, recording. Both share the same open-source integration core, @neurosquad/core. Use nsq when you live in the terminal, work over SSH or on Linux servers, or want something small and open; use the desktop app when you want the canvas.

Contributions are welcome — every change goes through a pull request. Read CONTRIBUTING.md and the Code of Conduct. Security issues: SECURITY.md. Questions and ideas: Discussions or our Discord. Releases: RELEASING.md.

Claude Code, Codex and OpenCode are trademarks of their respective owners. nsq uses their names only to describe which CLI an agent runs; this does not imply any partnership with, endorsement of, or affiliation with NeuroSquad. Claude Code is shown as a CC monogram on Claude's orange, at Anthropic's request — nsq ships no Claude Code logo. The other CLIs' icons only identify them; we remove one if its owner asks. Prefer no third-party icons or brand colours? Set NSQ_LOGOS=none: each CLI then gets its two-letter monogram on a neutral chip.

MIT © 2026 Stanislav Gelman and NeuroSquad contributors