// 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

Windows · PowerShell

$winget install OpenJS.NodeJS.LTS

$node -v# reopen the terminal first

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.

Wire the Claude Code hooks

One-time setup. This registers the local hooks Solix listens to for session, tool-call, and permission events.

one-time setup

$solix install

It's idempotent — safe to re-run any time, and solix uninstall removes it cleanly.

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. A planet flaring red is waiting on you: press Y or N.

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.

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 `solix install` wired the hooks. 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

Re-run `solix install` and check `solix doctor`. 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, Linux, Windows.

View on GitHub npm package