Neo

Appearance

Installing Neo ​

Neo needs Node.js >= 22. There are three ways to install it; pick the one that matches how you want to use Neo.

PathBest forCommand
npmMost usersnpm install -g @nehoraihadad/neo-agent
One-line installerA fresh machine, no npm experience neededsee below
Dev cloneContributing, running from sourcegit clone + pnpm setup

After any of these, run neo onboard (or just start neo — it offers onboarding automatically the first time it finds no provider credentials).

1. npm ​

bash
npm install -g @nehoraihadad/neo-agent
neo onboard

This installs the neo (and neo-stats, neo-tg, neo-wa, neo-live-driver) binaries globally, per package.json's bin field. Re-running npm install -g @nehoraihadad/neo-agent later upgrades in place — this is also what neo update does for you (see Updating below).

2. One-line installer ​

The installer scripts (install/install.sh, install/install.ps1) check Node, run the npm install, add npm's global bin directory to your user PATH when needed, verify neo --version, and launch neo onboard if you're in an interactive terminal. A new terminal can therefore start Neo with just neo.

macOS / Linux (install/install.sh — POSIX sh, no dependencies beyond npm):

bash
curl -fsSL https://raw.githubusercontent.com/NehoraiHadad/neo/main/install/install.sh | sh

Pass flags through the pipe with sh -s --, e.g. a dry run that checks prerequisites and prints the plan without installing anything:

bash
curl -fsSL https://raw.githubusercontent.com/NehoraiHadad/neo/main/install/install.sh | sh -s -- --dry-run

Windows (PowerShell) (install/install.ps1):

powershell
irm https://raw.githubusercontent.com/NehoraiHadad/neo/main/install/install.ps1 | iex

If your execution policy blocks running scripts directly, iex (used above) does not go through the script execution policy, so the one-liner works as written. To run a downloaded copy of the script directly instead:

powershell
powershell -ExecutionPolicy Bypass -File install.ps1

install.ps1 also checks for Git for Windows (Git Bash) on PATH — Neo's bash tool shells out to it. A missing install is a warning, not a fatal error (neo doctor re-flags it later); the suggested fix is:

powershell
winget install --id Git.Git -e --source winget

and for Node itself, if missing or too old:

powershell
winget install OpenJS.NodeJS.LTS

-DryRun / --dry-run ​

Both installer scripts accept a dry-run flag that checks prerequisites (Node version, and Git on Windows) and prints the install plan without installing or changing anything — useful for CI or verifying a machine before committing to the real install.

3. Dev clone ​

For contributing to Neo, or running straight from source:

bash
git clone https://github.com/NehoraiHadad/neo.git
cd neo
pnpm setup

pnpm setup runs node scripts/setup.mjs, which (in order):

  1. Checks the Node version (>=22).
  2. Checks for pnpm on PATH, running corepack enable if it's missing (corepack ships with Node >=22) — Neo pins pnpm@10.x via package.json's packageManager field.
  3. Runs pnpm install.
  4. Verifies better-sqlite3's native bindings load. If they don't (common on Windows, since pnpm blocks postinstall build scripts for native deps by default), it remediates automatically: first trying pnpm approve-builds better-sqlite3 (interactive TTY only), then falling back to pnpm rebuild better-sqlite3 (non-interactive-safe). You can run either of these yourself if setup didn't catch it — see Troubleshooting below.
  5. On Windows, checks for Git Bash (warning only, not fatal — see the Windows section above).
  6. Runs pnpm build.
  7. Runs pnpm link --global, adds pnpm's global bin directory to your user PATH when needed, and verifies neo --version. This is automatic; pass --no-link only when you explicitly do not want a global dev command.
  8. Runs neo doctor as a final summary (its own warnings/failures don't fail setup — only a broken build does).

Useful flags: node scripts/setup.mjs --ci (CI mode: no global link), --no-link (explicitly opt out of installing the global dev command), --skip-build (skip pnpm build, e.g. when a prior CI step already built), --self-test (runs setup's own pure-function assertions and exits — no install/build/network).

Troubleshooting ​

EACCES / permission denied on npm install -g ​

npm's global prefix usually isn't writable by your user when it points at a system directory. Point it at your home directory instead of reaching for sudo:

bash
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile && . ~/.profile

On Windows, the equivalent is to avoid an elevated (Administrator) PowerShell — that can leave files owned by a different account than the one you use day to day — and instead point npm's prefix at a folder you own:

powershell
npm config set prefix "$env:LOCALAPPDATA\npm"
[Environment]::SetEnvironmentVariable('Path', "$env:LOCALAPPDATA\npm;$env:Path", 'User')

Then open a new shell and retry.

better-sqlite3 fails to load (dev clone) ​

If node -e "require('better-sqlite3')" fails after pnpm install, the native binding didn't build/download for your platform. pnpm setup handles this automatically (see step 4 above); to do it by hand:

bash
pnpm approve-builds better-sqlite3   # interactive TTY checkbox picker
# or, non-interactively:
pnpm rebuild better-sqlite3

If that still fails, install a C++ toolchain so node-gyp can compile from source (Windows: Visual Studio Build Tools with "Desktop development with C++"), and make sure nothing else (a running Neo daemon from this checkout) has the native .node file locked, then retry.

neo resolves to the wrong install (PATH-shadowing) ​

If you've installed Neo more than one way (e.g. both npm install -g and a linked dev clone), the shell may run a different neo than you expect. neo doctor includes a PATH-shadowing check that compares the neo your shell would resolve from PATH against the one actually running, and tells you exactly which two installs are in conflict. Fix by reordering PATH so the intended install comes first, or removing the stale one (npm rm -g @nehoraihadad/neo-agent, or unlinking the dev clone with pnpm unlink --global).

neo not found after install ​

The one-line installers and pnpm setup persist the relevant global bin directory in your user PATH and verify the command before completing. If you used bare npm install -g with a custom npm prefix, add that prefix manually or re-run the one-line installer; then open a new shell.

Updating ​

bash
neo update            # apply the latest release
neo update --check    # report current vs. latest version only; don't change anything

neo update detects how the running build was installed (a .git directory next to its package root means a dev clone) and does the right thing either way:

  • npm install → runs npm i -g @nehoraihadad/neo-agent@latest for you, with install output streamed live.
  • git clone → does not run anything; it prints the guidance instead: git pull && pnpm install && pnpm build.

Neo also does a passive, opt-out check against the npm registry (registry.npmjs.org/@nehoraihadad%2Fneo-agent/latest, 5s timeout, cached ~24h) to power the TUI's update banner — no data is sent beyond that request. Disable it with NEO_UPDATE_CHECK=off. See docs/user/env-vars.md and docs/user/privacy.md.

Uninstalling ​

bash
neo uninstall --dry-run   # print the full plan; change nothing
neo uninstall             # interactive: prompts before each destructive step
neo uninstall --yes       # non-interactive: confirm every step up front

neo uninstall removes Neo's OS-level footprint — the daemon autostart service, configured channel logins, and OS-keychain secrets — then prints exactly what's left under ~/.neo (or $NEO_HOME) and the precise platform-appropriate command to delete it yourself.

neo uninstall never deletes ~/.neo. That decision, and the CLI package itself, are left to you:

  • Remove the CLI: npm uninstall -g @nehoraihadad/neo-agent (npm install), or just delete the cloned directory (dev clone — neo uninstall detects and tells you which applies).
  • Remove your data: the command it prints, e.g. rm -rf ~/.neo / Remove-Item -Recurse -Force ~/.neo.

Run neo export --all first if you want to keep a copy of your sessions/memory/config — see docs/user/uninstall.md for the full export/restore reference.

See also ​