Installation

ZO has three required dependencies: Claude Code CLI, Python 3.11+ with uv, and tmux. The bundled setup.sh installs them interactively if missing.

Quick install (recommended)

git clone https://github.com/SamPlvs/zero-operators.git
cd zero-operators
./setup.sh

setup.sh runs eleven validation checks and offers to fix each failure interactively:

OS detection

Confirms macOS or Linux. Other platforms are unsupported in v1.

Bash version

macOS ships bash 3.2; ZO scripts are 3.2-compatible (see PR-010 for why).

Python 3.11+

Required for type-hint syntax used throughout src/zo/.

Astral’s package manager. Installed via curl -LsSf https://astral.sh/uv/install.sh | sh if missing.

Claude CLI

Installed via curl -fsSL claude.ai/install.sh | bash if missing. The CLI handles auth on first launch.

tmux

Required for the conversational init/draft/build flow. Optional if you only use --no-tmux headless mode.

Git state

Confirms you’re inside a git repo (ZO uses git for worktree detection and commit conventions).

Project deps via uv sync

Resolves and installs pyproject.toml dependencies, pydantic, fastembed, click, rich, pyyaml.

Agent definitions

Confirms 21 agent .md files in .claude/agents/.

Slash commands

Confirms 24 commands in .claude/commands/.

zo on PATH

Symlinks .venv/bin/zo into ~/.local/bin/zo so the CLI is callable from any shell (handles conda/pyenv/system-Python users, see PR-012).

After it succeeds:

zo --version
# cli, version 1.0.2

Manual install

If you prefer to install dependencies yourself:

macOS (Homebrew)
Linux (apt)

# Python 3.11+, comes with macOS 14+ or via brew
brew install python@3.11

# uv, fast Python package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# tmux
brew install tmux

# Claude CLI
curl -fsSL claude.ai/install.sh | bash

# Clone and install ZO
git clone https://github.com/SamPlvs/zero-operators.git
cd zero-operators
uv sync
ln -sf "$(pwd)/.venv/bin/zo" ~/.local/bin/zo

zo --version

# Python 3.11+
sudo apt update && sudo apt install -y python3.11 python3.11-venv

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# tmux
sudo apt install -y tmux

# Claude CLI
curl -fsSL claude.ai/install.sh | bash

# Clone and install ZO
git clone https://github.com/SamPlvs/zero-operators.git
cd zero-operators
uv sync
ln -sf "$(pwd)/.venv/bin/zo" ~/.local/bin/zo

zo --version

Optional: GPU support

ZO’s Docker scaffold is platform-aware:

Linux + NVIDIA GPU + NVIDIA Container Toolkit → emits a GPU compose template with deploy.resources.reservations.devices: capabilities: [gpu].
macOS → emits a CPU compose template (Docker Desktop on Mac has no GPU passthrough; for hardware acceleration, run training natively with uv run python -m src.engineering.trainer to use Apple Silicon MPS).
Linux without GPU → CPU compose.

Detection runs at zo init time via zo.environment.detect_environment(). Override with --gpu-host or --base-image if needed.

Verifying the install

After installation, run the test suite to confirm everything wires up:

PYTHONPATH=src pytest tests/ -q
# 743 passed, 7 skipped in 5s

And run preflight on the bundled MNIST plan:

zo preflight plans/mnist-digit-classifier.md
# 6/7 passed, 1 warnings, 0 failures.
# Ready for zo build.

If anything fails, check troubleshooting, most issues are covered by the priors documented there.

Quickstart

Five minutes from zero to a real ML run.

Concepts

Mental model: plan, oracle, agents, gates, memory.

Get started

Concepts

CLI reference

Reference

Project

Quick install (recommended)

Manual install

Optional: GPU support

Verifying the install

Next

Quickstart

Concepts

​Quick install (recommended)

​Manual install

​Optional: GPU support

​Verifying the install

​Next

Quickstart

Concepts

Quick install (recommended)

Manual install

Optional: GPU support

Verifying the install

Next