Complete Getting Started Guide¶

This guide installs SuperQode and starts a normal coding-agent session. Use the agent or model you already prefer, switch harnesses when the task changes, and create your own HarnessSpec only when you need a durable project contract.

SuperQode is your portable coding agent harness. A harness defines the run contract: model policy, runtime backend, tool access, sandbox policy, workflow shape, events, and output handling.

1. Install¶

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

This installs uv when it is missing, then installs SuperQode in an isolated environment without sudo. If you already have uv, you can install it yourself instead:

uv tool install superqode      # persistent install
uvx superqode                  # run once without installing

Optional runtime backends are installed only when you need them:

uv tool install "superqode[openai-agents]"
uv tool install "superqode[pydanticai]"
uv tool install "superqode[deepagents]"
uv tool install "superqode[adk]"

For Codex, GitHub Copilot SDK, Claude Agent SDK, and Antigravity SDK support, install one runtime or the optional bundle:

uv tool install "superqode[codex-sdk]"
uv tool install "superqode[copilot-sdk]"
uv tool install "superqode[claude-agent-sdk]"
uv tool install "superqode[antigravity-sdk]"
# Or install the complete vendor SDK bundle:
uv tool install "superqode[vendor-sdks]"

The bundle does not include the Grok or agy subscription CLIs. Run superqode runtime setup for installation and authentication guidance.

2. Prerequisites¶

Before starting the TUI, make sure you have one of these ready:

• Signed-in coding agent such as Codex, GitHub Copilot, Antigravity, Grok, Kimi Code, Qwen Code, OpenCode, or another ACP agent
• API key for a cloud provider (set as env var like ANTHROPIC_API_KEY)
• Local model server running (e.g., ollama serve, mlx_lm.server)

See Connection Methods and Vendors for the centralized coding-agent, harness, provider, and local-model inventory.

3. Run The TUI¶

For interactive coding work:

cd /path/to/your/project
superqode

Once the TUI starts, connect a provider or agent:

:connect

Choose BYOK (cloud API key), Local (self-hosted model), ACP (coding agent), or an available SDK product profile from the picker. See Connection Methods and Vendors for the full connection and interoperability inventory.

Direct coding-agent examples:

:connect codex
:connect copilot
:connect antigravity
:connect grok
:connect kimi-code
:connect qwen-code
:connect acp opencode

For ACP coding agents, :connect acp shows installed and featured runtimes. Use :connect acp all to search the complete catalog or :connect acp refresh to update the cached official registry.

Useful TUI commands after connecting:

For local models, the fastest path to a harness you own is:

superqode local init --repo .
superqode --harness superqode.local.yaml

local init detects the machine, writes superqode.local.yaml, and runs a non-destructive smoke check when a local server is available. Use :local build or superqode local build when you already know the model, endpoint, or pack you want to target. The pack is only the starting point; inspect the generated YAML and customize model policy, memory, tools, and approvals for your project.

superqode.local.yaml is a harness file, not project configuration. Load it with superqode --harness superqode.local.yaml or :harness superqode.local.yaml. Use superqode config init separately when you want a project-level superqode.yaml.

You can also ask directly in natural language:

Summarize this repository and suggest the smallest safe improvement.

This is the first SuperQode use case: work in the repository as you would with another coding agent. A custom HarnessSpec is not required.

Switch the harness during the session¶

Open the unified Harness Switcher:

:harness
:harness switch

The picker includes built-in and project HarnessSpecs, vendor coding agents, ACP agents, optional integrations such as Hugging Face Tau, installed Python harnesses, registry harnesses, and model presets. Select a different harness for the next turn, or fork when the new harness should start an independent conversation branch.

Direct examples:

:harness switch workbench
:harness switch kimi-code --fork
:harness current

4. Run One Headless Task¶

For a quick terminal task:

superqode --print "summarize this repository"

For JSON output:

superqode --mode json --print "summarize this repository"

5. Create A Harness When Ready¶

Create a reusable coding harness:

superqode harness init my-coder --template coding --output harness.yaml

Check it before running:

superqode harness doctor --spec harness.yaml

Run it:

superqode harness run --spec harness.yaml --prompt "summarize the architecture"

For complete starting points, use the repository examples in examples/harnesses/. They cover the builtin coding harness, no-tool reasoning, PydanticAI, DeepAgents, OpenAI Agents SDK, Google ADK, Gemma4, and DS4.

The JSON form includes the run_id:

superqode harness run --spec harness.yaml --prompt "summarize the architecture" --json

6. Inspect What Happened¶

Every HarnessSpec run writes normalized events and a graph view.

superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness graph <run-id> --json

Use this when a run behaves unexpectedly. The graph gives one inspection model across backends.

7. Pick The Right Template¶

List templates:

superqode harness list-templates

8. Choose A Runtime¶

List backends:

superqode harness list-backends

Run with a backend override:

superqode harness run --spec harness.yaml --runtime pydanticai --prompt "review this design"
superqode harness run --spec harness.yaml --runtime openai-agents --prompt "make the smallest safe fix"
superqode harness run --spec harness.yaml --runtime deepagents --prompt "prototype the implementation"

Use doctor with the same override before a team run:

superqode harness doctor --spec harness.yaml --runtime pydanticai

9. Common Commands¶

10. Harness Checks¶

Project checks are part of a harness. Add commands under checks.custom_steps, then run the harness or inspect it with doctor.

checks:
  enabled: true
  fail_on_error: false
  timeout_seconds: 300
  custom_steps:
    - name: tests
      command: uv run pytest
      enabled: true
      timeout: 300

superqode harness validate --spec harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "make the smallest safe fix and run the configured check"

Use this path for repeatable project checks. For day-to-day coding, start with the TUI and focused prompts.

Next Steps¶

1. Your First Session
2. Connection Methods and Vendors
3. Bring Your Own Harness
4. Harness System
5. Running, Measuring, and Optimizing a Harness
6. Runtime Backends
7. Configuration Guide

Tips¶