// Install guide

Install Solix, properly.

Ten minutes from zero to a live galaxy — including getting Node 20+ and Claude Code set up if you don't have them yet. Everything runs on 127.0.0.1; nothing leaves your machine.

Install Node ≥ 20

Check what you have first. If it prints v20 or higher, skip to step 2.

check node

$node -v

macOS / Linux — nvm (recommended)

macOS / Linux

$curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

$nvm install 22# any LTS ≥ 20

$nvm use 22

Windows (via WSL)

Windows · PowerShell, then inside WSL

$wsl --install# then reopen and enter WSL

$curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

$nvm install 22

Solix's hooks are POSIX shell scripts, so run it inside WSL rather than native PowerShell — install Node, Claude Code and Solix all within WSL and the rest of this guide applies unchanged. Native Windows support is not there yet.

Node 20 is the floor because Solix uses the built-in WebSocket and fetch APIs. Node 22 LTS is what we test on.

Install Claude Code (optional)

Solix visualises Claude Code sessions, so you need Claude Code to watch real agents. You can skip this step and still explore the whole UI with solix demo.

claude code

$npm i -g @anthropic-ai/claude-code

$claude# sign in on first run

Run claude once in a project folder and complete the sign-in. That creates the settings file Solix adds its hooks to in step 4.

Solix never sees your Anthropic credentials. It reads the local hook events Claude Code emits on your machine — nothing more.

Install the Solix CLI

solix cli

$npm i -g @shmulikdav/solix

$solix --version

Prefer not to install globally? Run it straight from npm: npx @shmulikdav/solix start.

The hooks wire themselves

Nothing to run. The first time you start Solix it registers the local hooks it listens to for session, tool-call and permission events, and prints exactly what it changed. It backs up ~/.claude/settings.json before merging, and only ever adds its own entries — other tools' hooks on the same events are left alone.

It re-wires itself after an upgrade too, since the hook scripts ship with the product and change between releases. solix uninstall removes them cleanly.

For scripted setups, or to force a re-wire, the explicit command is still there:

optional

$solix install# idempotent

$solix install --force# re-wire now

Start mission control

launch

$solix start# → http://127.0.0.1:4242

$solix start --port 4300# if 4242 is taken

Open the URL, then start your Claude Code sessions as usual — each one appears as a planet within a second or two, with its live cost. Those sessions keep Claude Code's own approval prompt; it is the tasks you launch from Solix that it gates. When one of those pauses for permission its planet flares red and the count shows on Decisions in the left rail. Open it to see the exact command or diff, then Y or N. Those keys only act while the panel is open, so you cannot approve a command you have not seen.

Verify your setup

verify

$solix doctor# node, hooks, port, permissions

$solix demo# seed a sample galaxy

solix doctor should report Node ≥ 20, hooks installed, and the port free. solix demo seeds planets, comet streaks, and a pending permission so you can confirm approvals work end to end.

The plugins (optional)

Two Claude Code plugins ship alongside the CLI. These commands are typed inside Claude Code, not in a shell — there is no $ prompt.

/plugin marketplace add shmulikdav/Solix/plugin install solix-band/plugin install solix-crew

solix-band puts pending decisions above your prompt with Approve and Deny beside the command, so you don't switch to the browser for the one thing that can't wait. It needs Solix running; if it draws nothing when you expected it to, /solix-band status says which of the three reasons it is.

solix-crew is the fifteen advisors as Claude Code subagents, plus /solix-review and /solix-audit. It needs no server and no account — you can run it without installing Solix at all.

Troubleshooting

`solix: command not found` after installing

Your global npm bin directory isn't on PATH. Run `npm prefix -g`, then add `<that path>/bin` to your shell profile (`~/.zshrc`, `~/.bashrc`). Restart the shell and try `solix --version` again.

`EACCES: permission denied` on npm i -g

Don't use sudo. Install Node through nvm (step 1) so the global prefix lives in your home directory, or set a user-owned prefix: `npm config set prefix ~/.npm-global`.

Port 4242 is already in use

Start on another port: `solix start --port 4300`. The browser tab will open on the port you pass.

Solix opens but the galaxy is empty

Solix only sees sessions started after the hooks were wired, which happens the first time you run `solix`. Restart your Claude Code sessions, or run `solix demo` to seed a sample galaxy and confirm the UI works.

Permission prompts don't appear in the browser

Run `solix doctor` — it reports whether the installed hooks match the running build. `solix install --force` re-wires them. The hooks live in your Claude Code settings; a manual edit to that file can drop them.

How do I uninstall?

`solix uninstall` removes the Claude Code hooks, then `npm rm -g @shmulikdav/solix` removes the CLI. No other files are left behind.

Requires Node ≥ 20. Claude Code is optional — solix demo runs without it; you only need Claude Code to watch your real agents. macOS and Linux — on Windows, run Solix inside WSL.

View on GitHub npm package