The harness layer for coding agents.
Discover, build, run, evaluate, and optimize coding-agent harnesses from one terminal.

Documentation  ·  Quick Start  ·  Harness Hub  ·  Website  ·  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.

Quick Start

curl -fsSL https://super-agentic.ai/superqode.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

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.

The Harness Hub

:hub opens a browsable catalog of 97 harnesses: SuperQode's native harnesses, vendor coding agents, the full ACP registry, optional runtimes, model presets, and the HarnessSpecs your own repository defines.

: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

55 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, Cursor, Grok, Devin, Factory Droid, Kiro
ACP agents	OpenCode, Goose, Gemini CLI, 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.

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.

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
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
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.