Skip to content

Getting Started

SuperQode is your portable coding agent harness. It gives developers a TUI and CLI for running coding agents with explicit model choice, tool access, sandbox policy, approvals, sessions, events, and repeatable HarnessSpec files.

This guide gets you from install to a useful first run.

Quick Navigation

  • Installation

    Install SuperQode and verify the command works.

    Install now

  • Quick Start

    Run the TUI, create a harness, run a headless task, and inspect events.

    Quick start

  • First Session

    Walk through a normal interactive coding session.

    First session

  • Configuration

    Configure project defaults, providers, ACP agents, local models, and MCP servers.

    Configure

  • Harness Examples

    Start from ready-to-run HarnessSpec examples.

    Examples

  • Troubleshooting

    Diagnose install, provider, runtime, harness, sandbox, MCP, and session issues.

    Troubleshooting

Prerequisites

Requirement Version Notes
Python 3.12+ Required for the Python package
pip or uv latest recommended uv tool install superqode gives an isolated install
Git 2.25+ Recommended for repository work and reviewing changes

Optional tools depend on your workflow:

Tool Use
Node.js and npm ACP agents, MCP servers, JavaScript tooling
Ollama, LM Studio, MLX, vLLM, SGLang, or DS4 Local model workflows
Docker or optional sandbox SDKs Container or remote sandbox profiles

1. Install

uv tool install superqode
superqode --version

python -m pip install superqode
superqode --version

git clone https://github.com/SuperagenticAI/superqode.git
cd superqode
python -m pip install -e .
superqode --version

2. Start The TUI

cd /path/to/your/project
superqode

Connect a model or agent:

:connect

Direct examples:

:connect byok openai gpt-4o-mini
:connect local ollama qwen3:8b
:connect acp opencode

Check state:

:status

Then ask a small first task:

Summarize this repository and suggest the smallest safe improvement.

3. Choose A Connection Path

Path Use when Setup
ACP You want an external coding agent with its own tool loop superqode agents list and superqode agents doctor <agent>
BYOK You want hosted providers with your own API keys Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, or another provider key
Local You want private or offline inference Start Ollama, LM Studio, MLX, vLLM, SGLang, DS4, or another local server
SDK You want to use your ChatGPT or Claude subscription, or vendor-native agent behavior :connect codex, :connect claude, or :connect antigravity in the TUI

See Connection Modes for how the four paths differ.

Provider diagnostics:

superqode providers doctor
superqode providers guide openai
superqode providers recommend coding

4. Create A Harness

A HarnessSpec makes a run repeatable. It controls runtime, model policy, tools, sandbox, approvals, checks, hooks, events, workflow, and output.

superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "summarize this repository"

Load it in the TUI:

:harness harness.yaml
:harness status

Built-in templates:

superqode harness list-templates

Common templates:

Template Purpose
coding Repository coding with file, search, edit, shell, todo, checks, and approvals
no-tool Model-only reasoning without repository or shell tools
gemma4-coding Gemma4 local coding starting point
gemma4-no-tool Gemma4 model-only reasoning
ds4-coding DS4 local coding starting point
ds4-fast-local Lower-latency DS4 local iteration

5. Run Headless

Use headless mode for scripts and one-off terminal tasks:

superqode --print "summarize this repository"
superqode --mode json --print "summarize this repository"
superqode --profile plan --print "plan the safest fix for the failing test"

Use a harness for repeatable headless behavior:

superqode harness run --spec harness.yaml --prompt "make the smallest safe fix and run the narrowest useful test"

6. Inspect Sessions And Runs

Sessions:

superqode sessions list
superqode sessions tree
superqode sessions show <session-id>
superqode sessions export <session-id> --format markdown --output session.md

Harness runs:

superqode harness runs
superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness evidence <run-id>

Portable share artifacts:

superqode share create <session-id>
superqode share import <artifact.superqode-share.json> --session-id imported

7. Common CLI Commands

Command Purpose
superqode Launch the TUI
superqode --print "..." Run one headless task
superqode doctor Check core environment health
superqode config init Create superqode.yaml
superqode providers doctor Check provider setup
superqode agents list List known ACP agents
superqode runtime list List runtime backends
superqode harness init ... Create a HarnessSpec
superqode harness doctor --spec harness.yaml Preflight a harness
superqode harness run --spec harness.yaml --prompt "..." Run a harness task
superqode memory status Check memory providers
superqode sandbox doctor Check sandbox providers
superqode trust doctor Audit local project trust inputs

Which Workflow Should I Use?

Use the TUI when:

  • exploring a repository
  • making interactive changes
  • reviewing tool calls and approvals
  • switching providers or runtimes during a session
  • exporting or sharing a conversation

Use headless CLI when:

  • scripting a single task
  • running in automation
  • collecting JSON output
  • running repeatable HarnessSpec tasks
  • inspecting persisted run events

Next Steps

  1. Quick Start
  2. Your First Session
  3. Configuration
  4. Inside the Agent Loop, to understand what the engine is doing for you
  5. Harness System
  6. Connection Modes
  7. CLI Reference