Getting Started¶
SuperQode is the open-source, terminal-first Agent Engineering framework for your code factory, with first-class support for local and open models. Start by using it as a normal coding agent: open a repository, connect the agent or model you already use, and ask for coding work. You can switch the active harness during the session without giving up the familiar coding-agent workflow.
Harness authoring, evaluation, and optimization come later. They let you turn a useful interactive setup into a repository-owned, measured, and improvable run contract.
The Developer Journey¶
Follow the documentation in this order:
| Stage | What you do | Start here |
|---|---|---|
| 1. Use | Install SuperQode and use it like another terminal coding agent | Installation and Your First Session |
| 2. Choose | Connect any supported coding agent, model provider, local model, or optional harness | Connection Methods and Vendors |
| 3. Switch | Change harnesses during a session while preserving or deliberately forking context | Your First Session: Choose Or Switch A Harness |
| 4. Build | Create a repository-owned HarnessSpec when the default or existing harnesses are not enough | Bring Your Own Harness |
| 5. Evaluate | Measure the harness against repeatable tasks and held-out checks | Running, Measuring, and Optimizing a Harness |
| 6. Optimize | Use MetaHarness or GEPA Omni only after the evaluation contract is meaningful | Optimization Story |
| 7. Promote | Stage, canary, activate, or roll back a proven harness | Harness Promotion |
Quick Navigation¶
-
Installation
Install SuperQode and verify the command works.
-
Use It As A Coding Agent
Connect an agent or model, ask for coding work, and switch harnesses during the session.
-
Quick Start
See the complete install, interactive, headless, harness, and inspection path in one guide.
-
Configuration
Configure project defaults, providers, ACP agents, local models, and MCP servers.
-
Harness Examples
Start from ready-to-run HarnessSpec examples.
-
Troubleshooting
Diagnose install, provider, runtime, harness, sandbox, MCP, and session issues.
Prerequisites¶
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.12+ | Required for the Python package |
| One-line installer | recommended | Installs uv when needed, then verifies an isolated SuperQode tool install |
| uv | direct | uv tool install superqode gives the same isolated tool 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¶
curl -fsSL https://super-agentic.ai/superqode.sh | sh
superqode --version
Installs uv when it is missing, then installs SuperQode in an isolated environment. No sudo required.
uv tool install superqode
superqode --version
Use this when you already have uv and prefer to manage the install yourself.
uvx superqode --version
git clone https://github.com/SuperagenticAI/superqode.git
cd superqode
uv sync --extra dev --extra docs
uv run superqode --version
Every method except source installs the latest SuperQode release from PyPI.
2. Start The TUI¶
cd /path/to/your/project
superqode
Connect a model or agent:
:connect
Direct examples:
:connect byok openai <openai-model>
: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 a supported vendor runtime or vendor-native agent behavior | :connect codex, :connect antigravity, or an explicit API-key runtime in the TUI |
See Connection Methods and Vendors for the supported connection methods, product profiles, providers, local engines, and ACP agents.
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¶
- Quick Start
- Your First Session
- Configuration
- Inside the Agent Loop, to understand what the engine is doing for you
- Harness System
- Connection Methods and Vendors
- CLI Reference