Installation¶

This guide covers the one-line SuperQode installer and direct uv installation, including verification, optional runtime extras, and troubleshooting.

Safety note (OSS): Run the open-source SuperQode in a safe, controlled environment (sandbox, VM, or low-risk machine). This reduces the blast radius for testing workflows and agent-driven actions.

Quick Install¶

Run the hosted installer on macOS, Linux, or WSL:

curl -fsSL https://super-agentic.ai/superqode.sh | sh

It:

• uses an existing uv installation when available;
• otherwise announces and runs Astral's official uv installer;
• installs the latest SuperQode release from PyPI in an isolated tool environment;
• verifies both superqode --version and sq --version; and
• never uses sudo.

If you prefer to inspect downloaded scripts before running them:

curl -fsSL https://super-agentic.ai/superqode.sh \
  -o superqode.sh
less superqode.sh
sh superqode.sh

Prefer to install it yourself?¶

The installer is the recommended path because it handles the uv bootstrap for you. If uv is already installed, the direct equivalent is:

uv tool install --upgrade --force superqode

Or run once without installing:

uvx superqode

Both are fully supported, so pick whichever fits your setup. See Installation Methods for the full comparison.

Verify the installed tool:

superqode --version

The installed package exposes two equivalent commands:

superqode harness list
sq harness list

sq is the short alias for every superqode command. The longer name remains the clearest choice for documentation, automation, and agents. For a one-off shorthand invocation without installing, use uvx --from superqode sq; uvx sq refers to a package named sq, not to SuperQode. If another application already owns sq on your PATH, continue using the unambiguous superqode command.

System Requirements¶

Minimum Requirements¶

Python Version Check¶

python3 --version
# Should output: Python 3.12.x or higher

If you need to install Python 3.12+:

brew install python@3.12

sudo apt update
sudo apt install python3.12 python3.12-venv

sudo apt update
sudo apt install python3.12 python3.12-venv

Installation Methods¶

Method 1: One-line installer (recommended)¶

curl -fsSL https://super-agentic.ai/superqode.sh | sh

Run the same command later to upgrade. Uninstall with:

uv tool uninstall superqode

Method 2: uv directly¶

Use uv for an isolated tool installation managed separately from project environments.

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

# Install SuperQode
uv tool install superqode

Method 3: uvx (No Persistent Install)¶

Run SuperQode directly through uv when you want a temporary command.

uvx superqode --version

Installing optional extras in one line¶

Set SUPERQODE_EXTRAS immediately before the installer. For example, install the Hugging Face Tau adapter:

curl -fsSL https://super-agentic.ai/superqode.sh |
  SUPERQODE_EXTRAS=tau sh

Multiple extras use commas:

curl -fsSL https://super-agentic.ai/superqode.sh |
  SUPERQODE_EXTRAS=tau,vendor-sdks sh

Release automation can install an exact published version with SUPERQODE_VERSION=0.2.68.

Installation for Developers¶

For contributors or those wanting the latest features:

# Clone the repository
git clone https://github.com/SuperagenticAI/superqode.git
cd superqode

# Install using uv (recommended for dev)
uv sync --extra dev --extra docs

# Verify installation
uv run superqode --version

Environment-Aware Extras¶

The TUI presents the normal packaged-product command and does not modify the environment until you run that command explicitly:

Do not add SuperQode to an unrelated application's dependencies merely to enable a CLI integration.

To install the Codex, GitHub Copilot, Claude Agent, and Antigravity SDK runtimes together, use the optional vendor-sdks extra. It is intentionally excluded from the default installation because the vendor packages are large and many users need only one of them.

uv tool install "superqode[vendor-sdks]"
superqode runtime setup

For direct package installs such as MLX, SuperQode targets the running interpreter explicitly:

uv pip install --python /path/to/superqode/python "mlx-lm>=0.31.0,<0.32.0"

Post-Installation Setup¶

1. Initialize Configuration¶

# In your project directory, create a repo config
cd /path/to/your/project
superqode config init

This creates superqode.yaml in the current directory with local-first defaults for Ollama and qwen3:8b.

2. Set Up Local Models¶

For the local-first path, start Ollama and pull a starter model:

ollama pull qwen3:8b

Then run superqode, use :local init, :connect local, and select superqode.local.yaml with :harness superqode.local.yaml.

3. Set Up API Keys (BYOK Mode)¶

For cloud providers, set your API keys as environment variables:

export ANTHROPIC_API_KEY=sk-ant-...

export OPENAI_API_KEY=sk-...

export GOOGLE_API_KEY=...
# or
export GEMINI_API_KEY=...

# SuperQode API Keys
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...
export DEEPSEEK_API_KEY=...
export GROQ_API_KEY=...

3. Verify Provider Configuration¶

# Check authentication status
superqode auth info

# List available providers
superqode providers list

# Test a specific provider
superqode providers test anthropic

Optional Dependencies¶

Install an extra into the same environment that runs SuperQode:

uv tool install "superqode[<extra>]"

The default install remains intentionally small. Install only the integrations used by the current repository or runtime.

Contributor and repository-maintenance extras are separate:

For Local Models¶

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama
ollama serve

# Pull a model
ollama pull qwen3:8b

uv pip install vllm

For ACP Agents¶

npm i -g opencode-ai

# Verify installation
opencode --version

Linting and Type Checking¶

Install language-specific linters for code analysis in harness runs:

uv pip install ruff mypy pyright

npm install -g eslint typescript

go install golang.org/x/lint/golint@latest
go install honnef.co/go/tools/cmd/staticcheck@latest

rustup component add clippy

Verify Installation¶

Basic Verification¶

# Check version
superqode --version

# View help
superqode --help

# Launch TUI
superqode

Full Verification¶

# Check all dependencies
superqode auth info

# List providers
superqode providers list

# List agents
superqode agents list

Expected Output¶

$ superqode --version
SuperQode v0.1.4

$ superqode auth info
╭─────────────────────────────────────────────────╮
│              Authentication Status               │
├─────────────────────────────────────────────────┤
│ Provider      │ Status    │ Model Access        │
├───────────────┼───────────┼─────────────────────┤
│ anthropic     │ ✓ Valid   │ <anthropic-model>     │
│ openai        │ ✓ Valid   │ <openai-model>             │
│ ollama        │ ✓ Running │ qwen3:8b            │
╰─────────────────────────────────────────────────╯

Troubleshooting¶

Common Issues¶

# Using pyenv
pyenv install 3.12.0
pyenv global 3.12.0

export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc  # or ~/.zshrc

uv tool install superqode

/Applications/Python\ 3.12/Install\ Certificates.command

ollama serve

Getting Help¶

If you encounter issues not covered here:

1. Check the GitHub Issues
2. Run with verbose logging: superqode --verbose

Upgrading¶

Upgrade SuperQode¶

uv tool upgrade superqode

Check for Updates¶

# View current version
superqode --version

# Check PyPI for latest version
pip index versions superqode

Uninstalling¶

uv tool uninstall superqode

Remove Configuration¶

# Remove user configuration
rm -rf ~/.superqode.yaml
rm -rf ~/.superqode/

# Remove project configurations
rm -rf .superqode/
rm -f superqode.yaml

Next Steps¶

• Quick Start Guide - Get started in 5 minutes
• Your First Session - Complete walkthrough
• Configuration - Customize SuperQode