Installation¶

This guide covers SuperQode installation, including prerequisites, 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¶

uv tool install superqode

Or using pip:

pip install superqode

That's it! Verify with:

superqode --version

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: uv (Primary Recommendation)¶

Best for performance and security. Use uv for the fastest installation and perfectly isolated tooling.

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

# Install SuperQode
uv tool install superqode

Method 2: pip (Primary Recommendation)¶

Standard installation via PyPI.

# Install SuperQode
pip install superqode

# Verify installation
superqode --version

Alternate Installation Methods (No Python Required)¶

These methods provide a pre-compiled binary for the SuperQode TUI. Validation workflows require the Python install (uv or pip). These methods are convenient for users who do not want to manage a Python environment, but may have a slightly slower startup time (~1-2 seconds) compared to the primary methods.

Method 3: Homebrew (macOS/Linux)¶

brew tap SuperagenticAI/superqode
brew install superqode

Method 4: Installer Script¶

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

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

# Or standard pip install
pip install -e ".[dev]"

# Verify installation
superqode --version

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 (project-level config).

2. 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¶

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

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:

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   │ claude-sonnet-4     │
│ openai        │ ✓ Valid   │ gpt-4o              │
│ 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

pip install --user superqode
# or use uv
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¶

pip install --upgrade superqode

uv tool upgrade superqode

Check for Updates¶

# View current version
superqode --version

# Check PyPI for latest version
pip index versions superqode

Uninstalling¶

pip uninstall superqode

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