Install xo

xo needs Python 3.11 or newer and git. The by-hand install below pins xo to 6e6d79b, the first commit whose spaces work on the quirq hub as it is now. qq-setup installs the commit in its pins.json; while that is older, use the hub after updating by hand to 6e6d79b. For GitHub, also install the GitHub CLI (gh): xo logs in to GitHub through it. For spaces on the quirq hub, also install the hub's client (below).

With qq-setup (one command)

qq-setup installs, updates and removes xo from a page in your browser. It needs Node 22 or newer. Replace <commit> with the full id of the latest commit on main:

npx --allow-remote=root https://codeload.github.com/quirq-ai/setup/tar.gz/<commit>

The page opens on step 1, This machine. Each tool starts at Keep (or Don't install). For xo, pick Install (or Update, Add to PATH or Remove when it is there), and leave qq as it is if you only want xo. Press Run: it runs the commands one at a time, with their output on the page. Then press Done: close qq-setup and open a new terminal.

• Linux and macOS: it makes a venv in ~/.xo and adds ~/.xo/bin to your PATH, in your shell's startup file (~/.zshrc, or for bash ~/.bashrc on Linux and ~/.bash_profile on a Mac). On a Mac with no new enough Python, it first runs brew install python@3.13.
• Windows: run the command in cmd or PowerShell. There it offers xo only (qq needs Linux, macOS or WSL). It makes the venv in %USERPROFILE%\.xo and adds %USERPROFILE%\.xo\Scripts to your user PATH. It uses python, else py; with neither new enough, it links python.org's Windows installer (tick "Add python.exe to PATH").

In a terminal without a browser, add install --only xo to the end of the command. --dry-run shows the commands without running them.

By hand (Mac or Linux)

You need Python 3.11 or newer (python3 --version; stock macOS ships 3.9, so run brew install python@3.13 and use python3.13 below), git, and on Debian or Ubuntu sudo apt install python3-venv. Using bash? Change ~/.zshrc (twice) to ~/.bash_profile on a Mac or ~/.bashrc on Linux.

python3 -m venv ~/.xo \
  && ~/.xo/bin/pip install "quirq-xo @ git+https://github.com/quirq-ai/xo@6e6d79b96310968278d3aab14ddc2b49c88642f3" \
  && { grep -qxF 'export PATH="$HOME/.xo/bin:$PATH"' ~/.zshrc 2>/dev/null || echo 'export PATH="$HOME/.xo/bin:$PATH"' >> ~/.zshrc; } \
  && export PATH="$HOME/.xo/bin:$PATH" \
  && xo --version

The last line prints xo 0.1.0 (6e6d79b): the version, then the commit it was installed from. If a step fails, the ones after it don't run.

Update or remove

The commands here are for Mac and Linux. On Windows, use qq-setup's Update and Remove.

To update by hand, replace NEW_SHA with the commit you were given:

~/.xo/bin/pip install --force-reinstall --no-deps "quirq-xo @ git+https://github.com/quirq-ai/xo@NEW_SHA"

xo --version shows which commit you have. qq-setup reports an xo at another commit instead of calling it out of date, since the XO team may have given you a newer one: its Update would move it to qq-setup's own pin, in its pins.json.

Auto-update

qq-setup can keep xo up to date for you. It is off until you turn it on: tick the Auto-update box on This machine, or in a terminal add install --auto-update to the end of its command (--no-auto-update turns it off). It then writes auto-update next to xo's key (in ~/.config/xo), naming the commit it installed.

• At most once a day, in the background, xo reads the commit qq-setup has reviewed (pins.json on its main), so no command waits on the network.
• When it is newer, the next command updates xo first, then runs on the new xo. If the update fails, the command runs on the xo you have. On Windows, where a running xo.exe cannot be replaced, xo updates right after the command instead.
• An xo you installed another way, or at another commit, is left alone until qq-setup's Update puts it back. Nothing runs when CI is set.
• What it did is in auto-update.log, next to the key.

Remove

To remove xo, log out first, so the saved key goes too, then delete its folder and the PATH line from your startup file:

xo logout
rm -rf ~/.xo
unset XO_API_KEY

qq-setup's Remove does the same: xo logout, then ~/.xo (or %USERPROFILE%\.xo on Windows) and its PATH entry. Run from the page, xo logout keeps your gh login; to log gh out too, run gh auth logout.

The quirq hub's client

xo create space puts a folder of repos on the quirq hub, and a space's xo update and xo sync push there. xo reaches the hub through its client, spacehub, which brings git's git-remote-quirq. It needs Node 22 or newer and git:

git clone https://github.com/quirq-ai/space-hub
space-hub/scripts/install-cli.sh

xo 6e6d79b needs a spacehub with a project command, and stops and says so when yours is older: run git pull in your space-hub folder, then scripts/install-cli.sh again.

Then run xo login (again): it hands your hub login to spacehub, and xo sh runs it on that hub (the hub). Without the client, spaces keep working with GitHub alone, and xo create space needs --github.

Next: log in.