Quick Start¶
Get a SuperQode harness running in a few minutes.
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.
Safe first run
Start in a low-risk repository, throwaway branch, sandbox, or VM. Coding harnesses can read files, edit files, and run shell commands when policy allows it.
1. Install¶
pip install superqode
Or with uv:
uv tool install superqode
Optional runtime backends are installed only when you need them:
pip install "superqode[openai-agents]"
pip install "superqode[pydanticai]"
pip install "superqode[deepagents]"
pip install "superqode[adk]"
2. Prerequisites¶
Before starting the TUI, make sure you have one of these ready:
- 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 BYOK providers or Local providers for setup guides.
No config file needed
SuperQode runs without a superqode.yaml. Just connect a model and start asking. The harness file, project defaults, and MCP servers are all optional extras you add with superqode init when you need them.
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), or ACP (coding agent) from the picker. See Connection Modes for guidance on which to pick.
Useful TUI commands after connecting:
| Command | Purpose |
|---|---|
:status | Show current provider, runtime, mode, and harness state |
:harness harness.yaml | Load a HarnessSpec into the session |
:runtime list | Show runtime backends |
:runtime pydanticai | Switch runtime where available |
:providers | Inspect provider setup |
:providers free | Find free/local inference setup paths |
:providers free --live openrouter | Scan current zero-price model routes |
:sandbox | Show or set the local command sandbox mode |
:theme | Pick an accent theme |
:compare <models> | Re-run your last message across several models |
:export | Export the conversation to HTML |
:rewind | Rewind the conversation to an earlier message |
:help | Show available commands |
You can also ask directly in natural language:
Summarize this repository and suggest the smallest safe improvement.
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¶
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.
| Backend | Rich graph events |
|---|---|
builtin | Model requests, model deltas, tools, results, approvals |
pydanticai | Model deltas, tools, results, approvals |
openai-agents | Model deltas, tools, approvals, sandbox markers |
deepagents | Model deltas, tools, subagents, memory, sandbox activity, results |
adk | Run and stream events |
7. Pick The Right Template¶
| Template | Use when |
|---|---|
coding | You want repository-aware coding with file/search/edit/shell tools under policy |
no-tool | You want model-only reasoning with no tools, shell, or repository access |
gemma4-coding | You want a Gemma4 local coding starting point |
gemma4-no-tool | You want Gemma4 model-only reasoning |
ds4-coding | You want a DS4 local coding starting point |
ds4-fast-local | You want lower-latency local DS4 iteration |
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¶
| Command | Purpose |
|---|---|
superqode | Launch the interactive TUI |
superqode --print "..." | Run one headless task |
superqode harness init ... | Create a HarnessSpec |
superqode harness validate --spec harness.yaml | Validate spec syntax |
superqode harness doctor --spec harness.yaml | Preflight a spec and backend |
superqode harness inspect --spec harness.yaml | Show resolved policy and compatibility |
superqode harness compile --spec harness.yaml --json | Show effective spec and model policy |
superqode harness diff old.yaml new.yaml | Compare two harness specs |
superqode harness run --spec harness.yaml --prompt "..." | Run a harness task |
superqode harness events <run-id> | Show normalized run events |
superqode harness graph <run-id> | Show the persisted event graph |
superqode providers doctor openai | Check provider setup |
superqode runtime list | List runtime backends |
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¶
Tips¶
Run doctor first
superqode harness doctor --spec harness.yaml catches missing optional runtimes, incompatible no-tool/coding settings, sandbox policy issues, and event-store problems.
Use no-tool for pure reasoning
The no-tool template intentionally removes filesystem, shell, network, and repository access.
Use the graph when debugging
superqode harness graph <run-id> --json is the best way to see what a backend actually emitted.