The harness layer for coding agents.
Discover, build, run, evaluate and optimize coding-agent harnesses from one terminal.
Interoperable over ACP, A2A, MCP and UHP: drive any coding agent, and be called as one.
Documentation · Quick Start · Harness Hub · superqode.dev · Demo · Discussions
What is SuperQode?
Picking a capable model does not give you a reliable code production system. The harness decides what the agent sees, which tools it may use, how it remembers, what it is allowed to change, and how its work gets verified. That layer is usually owned by a vendor, invisible, and impossible to measure.
SuperQode makes the harness a repository-owned artifact you can read, version,
test, and improve. One portable HarnessSpec controls the runtime, model
policy, tools, memory, search, sandbox, approvals, workflow, and evidence.
Connect the coding agents you already pay for, run local or hosted models, or build your own harness. All of them run through the same inspectable contract.
Demo
One session: connect an agent, browse the Harness Hub, and call the A2A agent from the same terminal.
Quick Start
curl -fsSL https://superqode.dev/install.sh | sh
The installer pulls the latest release from PyPI into an isolated environment,
installs uv when needed, and never uses sudo.
Already have uv? Run uv tool install superqode instead.
Open any repository and start:
cd your-project
superqode
Connect something, then work normally:
:connect # local models, ACP agents, BYOK, or a vendor plan
:connect codex # or claude, copilot, grok, kimi-code, qwen-code, fx
Summarize this repository and identify the smallest safe improvement.
Prefer a single headless task?
superqode --print "fix the failing test and summarize the change"
sq is a shorter alias for every superqode command. Remove it any time with
uv tool uninstall superqode.
Four ways in, from the same install:
superqode # coding agent TUI
:connect acp opencode # drive any ACP agent
:connect ollama # local models / airplane mode
superqode connect a2a --url https://a2a.superqode.dev
The Harness Hub
:hub opens a browsable catalog of 104 harnesses: SuperQode's native
harnesses, vendor coding agents, the full ACP registry, optional runtimes,
model presets, and the HarnessSpecs your own repository defines. The same
catalog is on the web at superqode.dev/hub.
:hub # browse, search, and filter every route
:harness switch codex # change harness mid-session, keeping the conversation
:harness switch rlm --fork # or branch into an independent attempt
64 of those harnesses are open source, across every route. Press o in the
Hub, or ask from the command line:
sq hub list --openness open
sq hub show deepagents
sq hub list --json # the same catalog, for scripts and dashboards
Openness describes the harness implementation, never SuperQode's route to it. A license SuperQode cannot verify is reported as unknown rather than guessed.
Bring Your Own Agent, or Build One
Connect an agent that already exists:
| Route | Examples |
|---|---|
| Vendor plans | Codex, Claude, GitHub Copilot, Grok, Devin, Factory Droid, Kiro |
| ACP agents | OpenCode, Goose, Cline, OpenHands, Deep Agents Code, and the full registry |
| Optional runtimes | LangChain DeepAgents, Hugging Face Tau, DeepSeek Harness, PydanticAI, Google ADK, OpenAI Agents SDK |
| Local models | Ollama, LM Studio, MLX, DS4, llama.cpp, vLLM, SGLang, TGI |
Or write your own. Start from the wizard, a template, or plain YAML:
superqode harness wizard
superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "review this repository"
Runnable examples live in examples/harnesses. An
independently installed Python harness needs one async function and one entry
point to join the catalog:
[project.entry-points."superqode.harnesses"]
my-harness = "my_package:run"
Native RLM
rlm is the built-in recursive harness. The model gets one executable tool and
a persistent Python environment, and builds context by writing Python instead of
calling separate search, edit, and shell tools:
chunks = context.select("src/**/*.py").chunk(size=8000)
answers = llm_query_batched([chunk.labelled() for chunk in chunks])
children = rlm.run_batch(["Inspect the implementation", "Inspect the tests"])
results = rlm.wait_all(children)
It runs on the host, in a container with sandbox: docker, or inside a
no-filesystem interpreter with sandbox: monty.
See Native RLM.
Evaluate and Optimize
Treat the harness the way you treat the rest of your code: measure it, then gate changes against repeatable tasks.
superqode harness test --spec harness.yaml
superqode harness eval --spec harness.yaml --tasks eval-tasks.yaml
superqode harness eval --spec harness.yaml --variant candidate.yaml --tasks eval-tasks.yaml
Evaluation records behavior and never edits the spec. Optimization is a separate outer loop, worth reaching for only once the tasks and scoring represent the behavior that matters:
superqode harness optimize-omni --spec harness.yaml --tasks eval-tasks.yaml --max-evals 20
superqode harness promote stage
Candidates stay reviewable artifacts. GEPA Omni stages its selected HarnessSpec separately, audits the mutation surfaces it is allowed to touch, and runs a sealed held-out gate without replacing the live specification.
See the evaluation and optimization guide and Harness Promotion.
Release records
Evaluation says how a harness scored. A record says what was checked before a change shipped, which conditions had to hold, who accepted it, and what to revert to.
sq gauge run --spec harness.yaml --tasks eval-tasks.yaml --out record.yaml
sq gauge gate record.yaml --level L2 # the CI verb
The format is SuperGauge, an open specification any tool may implement. SuperQode computes nothing new for it: the record projects the eval result, the execution policy, the governance decisions, the promotion registry and the event ledger it already holds. See Agent Quality Records.
Local and Open Models
SuperQode is tuned for the cases where context, tool calling, and search decide whether an agent works at all:
- Auto context management detects the loaded context window and compacts before overflow.
- Context economy uses bounded reads, line-numbered output, continue hints, spill files, and stale-output pruning.
- Local search registers repositories with
:workspace add, searches with ripgrep, and adds semantic indexes when needed. - Airplane Mode prepares a strict offline harness with network tools removed.
- Post-edit verification feeds fast per-file checks back to the agent so it can correct itself before moving on.
- Resilient tool calls repair malformed calls and block no-progress loops.
superqode local init --repo . # detect hardware, generate a starter harness
superqode providers scan-free # find current zero-price model routes
Local inference uses real CPU, GPU, memory, and battery. Prefer smaller models or hosted providers when a machine is constrained.
Code Factory Workflows
For work that has to finish across several harnesses, use a durable WorkOrder with bounded workers, isolated worktrees, crash recovery, acceptance checks, and an explicit human delivery decision:
sq work create "Implement and review the authentication fix" \
--repo . --harness coding \
--acceptance-test "uv run pytest -q tests/test_auth.py" --queue
sq work worker --id builder-01 --concurrency 2
sq work approve work_... --actor maintainer
sq work merge work_... --actor maintainer --cleanup
Read the Code Factory guide.
Serve a Harness Over A2A
Everything above describes SuperQode as something you run. It also runs as an Agent2Agent agent that other systems call, which is how a harness reaches an orchestrator, a multiplayer agent computer, or a host platform such as Gemini Enterprise or Microsoft Foundry.
superqode serve a2a --spec harness.yaml
Discovery is a published Agent Card. One card advertises JSON-RPC and HTTP+JSON
across A2A 1.0 and 0.3, so a single document satisfies every registration path.
The public SuperQode agent runs at
a2a.superqode.dev and you
can call it today:
superqode connect a2a --url https://a2a.superqode.dev
It scores 100% of MUST and 100% of MAY against the Technology Compatibility Kit the A2A project maintains under the Linux Foundation, on the JSON-RPC and HTTP+JSON transports the card declares. Reproducing that run is documented in the A2A guide.
A remote bind is deliberate about what it exposes. It serves the
harness-shortlist skill, which answers questions about which coding agents and
harnesses to consider from the curated Harness Hub without touching a
repository. Running harnesses remotely requires opting in with --expose-harness
and naming the spec, because the spec decides what an accepted request may do.
Callers are identified by signed API keys that carry a customer, tier and expiry, and are verified without a database:
superqode a2a-keys issue "Acme Corp" --tier one-off --days 30
Read the A2A guide.
Harness Execution Model
1. SPEC Choose coding, no-tool, local-model, or custom behavior
2. MODEL Resolve local or hosted model policy
3. RUNTIME Run on builtin, an SDK, ACP, or another backend
4. TOOLS Attach file, search, edit, shell, MCP, or no tools
5. SESSION Stream events, persist history, and compact context
6. OUTPUT Return text, typed data, workflow results, and validation
Sessions are durable and the harness is replaceable. Switching keeps the session ID and replays stored context through the newly selected harness.
SuperQode also normalizes each runtime's own stream into one event graph, so a run is inspectable the same way regardless of the framework underneath:
| Backend | Rich graph events |
|---|---|
builtin |
Model requests, deltas, tool calls, results, approvals, final output |
deepagents |
Model deltas, tools, subagents, memory, sandbox events, final output |
codex-sdk |
Model deltas, command output, patches, file changes, completion |
openai-agents |
Model deltas, tool calls, results, approvals, sandbox markers |
pydanticai |
Model deltas, tool calls, results, approval pauses, final output |
adk |
Run and stream events using the shared graph storage contract |
superqode harness events <run-id>
superqode harness graph <run-id> --json
Documentation
| Guide | What it covers |
|---|---|
| Website | Product, Hub, A2A agent |
| Quick Start | Install, connect, and run your first task |
| Harness Hub | Browsing, filtering, and the published catalog |
| Connection Methods | Local, ACP, BYOK, SDK, MCP, and A2A routes |
| A2A Agents | Serving a harness over A2A, skills, API keys, and the Agent Card |
| Developer Workflows | The complete TUI and CLI command set |
| Harness System | HarnessSpec fields, runtimes, and policy |
| Harness Protocol | The versioned session and evidence contract |
| Bring Your Own Harness | Templates, wizard, and repository specs |
Contributing
Contributions are welcome. See CONTRIBUTING.md.
git clone https://github.com/SuperagenticAI/superqode
cd superqode
uv sync --extra dev --extra docs
uv run pytest
License
Apache-2.0, built by Superagentic AI.
1 maintainer
Release files for superqode 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| superqode-2.1.0.tar.gz | 2.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| superqode-2.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.5 MB
Release files / superqode-2.1.0.tar.gz
| Download URL | superqode-2.1.0.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
20cb7cb303250ead86aa40e9061d722b540922f30b08f309a0863e24124d4cd4
|
|
BLAKE2b-256 checksum How to use checksums |
7254e86295de504dc1d1342e79632ae60e4b601800f214aed8819a96e6f9f872
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / superqode-2.1.0-py3-none-any.whl
| Download URL | superqode-2.1.0-py3-none-any.whl |
|---|---|
| Size | 2.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9dd9f80dc7e89799d60e6a3a027a42c10a339be9c906df82e6082ff4b3ecefc8
|
|
BLAKE2b-256 checksum How to use checksums |
8123036cf01177dbe9524d0d57de4f6ce7546d676e9b542185df4e8275f5b4b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
