SuperQode¶

Agent Engineering for Your Code Factory

Build your own coding-agent harnesses or connect the agents you already use. Orchestrate, evaluate, govern, and optimize how they work across your repositories.

Terminal-first · Any agent · Any model · Local or cloud · Open source

Start Coding Choose an Agent, Model, or Harness Build Your First Harness Optimize Local Models SuperQode Website

SuperQode Agent Engineering terminal workbench

Installation and first run¶

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

The installer adds uv when needed, installs the latest SuperQode release from PyPI in an isolated environment, and verifies the command. It does not use sudo.

Already have uv? Install it yourself instead:

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

The command starts the interactive TUI. Connect the coding agent or model you already use:

:connect                               # open the complete connection picker
:connect codex                         # Codex subscription
:connect copilot                       # GitHub Copilot plan (SDK or CLI)
:connect kimi-code                     # Kimi Code through its official ACP server
:connect qwen-code                     # Qwen Code through its official ACP server
:connect acp <agent>                   # any installed ACP coding agent
:connect local ollama <open-model>     # a local server you run
:connect byok <provider> <model>       # a hosted provider with an API key

Ask for repository work as you would in another coding agent:

Summarize this repository and identify the smallest safe improvement.

Switch the complete harness without leaving the session:

:harness
:harness switch
:harness switch qwen-code --fork

The Harness Switcher includes SuperQode's native harnesses, project HarnessSpecs, vendor and ACP coding agents, model presets, installed and registry harnesses, and optional integrations such as Hugging Face Tau.

For noninteractive execution and CI, see the headless examples below. Build a repository-owned HarnessSpec only when you want to make the working behavior repeatable and reviewable.

For local and open models, generate a repository-owned starter harness:

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

Use local init to detect the current system and generate a default HarnessSpec. Use local build to select a specific model, endpoint, or model pack.

A progressive way to adopt SuperQode¶

Stage	Developer outcome	Documentation
Use	Work in a repository with a familiar coding-agent experience	Your First Session
Choose and switch	Select any supported agent, model, provider, or harness and switch during the session	All Connections
Build	Create a repository-owned HarnessSpec for repeatable behavior	Bring Your Own Harness
Evaluate	Measure behavior with tasks, scorecards, and regression gates	Run, Measure, Optimize
Optimize	Generate staged candidates only after the evaluation contract is useful	Optimization Story
Promote	Canary, activate, and roll back a proven harness	Harness Promotion

Overview¶

SuperQode is the open-source, terminal-first Agent Engineering framework for your code factory. It provides the lifecycle for building, connecting, orchestrating, evaluating, governing, and optimizing reliable coding-agent harnesses across your repositories.

Agent Engineering is the discipline of designing, building, evaluating, governing, and operating agents as reliable systems. SuperQode applies that discipline to your code factory: the organization-owned system of agents, harnesses, models, context, tools, repositories, policies, and evaluation gates that turns intent into verified code changes.

Harness engineering is one discipline within Agent Engineering. The repository-owned HarnessSpec defines model routing, tools, memory, context, search, approvals, sandboxing, workflows, evaluation, and optimization. Reliable delivery and harness independence are the outcomes.

SuperQode is terminal-first by design. The CLI and TUI are the complete primary product surfaces for building harnesses, coordinating sessions and WorkOrders, reviewing evidence, and approving delivery. Browser rendering, the local companion API, and chat channels provide optional remote access without creating a separate web or mobile product direction.

The problem SuperQode solves¶

Selecting a capable model does not give an organization a reliable code production system. The harness still decides what the agent sees, which tools it can use, how it remembers, what it may change, and how its work is verified.

Teams commonly face several related problems:

established coding agents provide useful but vendor-owned harnesses that cannot always be inspected, moved, or evaluated independently
open and local models provide model capability without a complete repository coding harness
different agents keep separate sessions, context, tools, permissions, and evidence
session orchestration alone does not ensure that repository work finishes, passes checks, or produces an exact candidate a human can approve
harness changes are difficult to compare when quality, cost, latency, regressions, and failed candidates are not recorded together

SuperQode makes the harness a repository-owned engineering artifact, connects existing agents through native runtimes and ACP, and applies a consistent lifecycle for execution, evaluation, governance, evidence, delivery, and optimization.

Where SuperQode fits¶

Two ownership boundaries distinguish coding-agent products: control of the model and control of the harness. The harness is the complete agent loop, including prompts, context strategy, tools, memory, permissions, workflow, and verification behavior.

Ecosystem pattern	Model choice	Harness ownership	Typical examples	Practical result
Closed model, closed harness	Primarily the vendor's models	The vendor owns and evolves the agent loop	Vendor coding agents such as Claude Code with Claude	The vendor manages model access and agent-loop changes as one product
Open or selectable models, closed harness	Several providers or model families may be available	The product vendor still controls the complete loop	Multi-model products such as Cursor	The team can select models, while the complete harness remains product-controlled
Open models, open harness	Hosted, open-weight, or local models	The agent implementation is open source and configurable	Cline, OpenCode, and Aider	The source and model routes are inspectable; execution generally follows the framework's established loop

These categories describe control boundaries and can overlap. SuperQode classifies an integration by whether the complete working contract can be stored in a repository, executed across agents and models, evaluated independently, and promoted as a reviewed revision.

Coding agents, static harnesses, meta-harnesses, and SuperQode¶

Layer	Primary purpose	What it provides	Relationship to SuperQode
Coding agent	Complete coding sessions	An interactive product with a built-in agent loop	SuperQode can connect supported coding agents and switch between them during a session
Static agent harness	Run a configurable agent loop	An implementation with prompts, tools, and model settings defined by that product or framework	SuperQode can run its own native harness or connect external harnesses while keeping a common session, policy, and evidence layer
Meta-harness or optimizer	Search for better prompts, code, configuration, or agent structure	Candidate generation and selection around an evaluator	SuperQode uses optimizers such as MetaHarness and GEPA Omni as optional stages in a guarded lifecycle
SuperQode	Engineer and operate the complete coding-agent lifecycle	Coding sessions, agent and model switching, repository-owned HarnessSpecs, evaluation, governance, optimization, and promotion	A terminal interface and versioned lifecycle for execution through approved harness revisions

Existing coding agents can remain part of the workflow. SuperQode can first operate as the coding interface and connection layer. A repository-owned HarnessSpec can be introduced when the team requires repeatable behavior and control of the agent loop. Evaluation, optimization, and promotion require a defined task contract.

Build your code factory¶

Build an organization-owned harness, select one from the catalog, or connect an existing coding agent through a native runtime or ACP. SuperQode operates them through one consistent system for orchestration, evaluation, governance, and optimization.

Understand Code Factories Read Harness Engineering

Agent Engineering lifecycle¶

Agent Engineering treats the complete agent lifecycle as an engineering system. SuperQode provides five connected capabilities for a coding harness you own.

Build

Author a harness as a versioned harness.yaml. Use the wizard, start from a model-family template, and read what it does in plain English with harness explain.

Bring Your Own Harness
Run

Execute the same contract across runtimes, providers, MCP, ACP, and A2A. Swap models, memory, search, or tools without rewriting the workflow.

Runtime Backends
Evaluate

Measure behavior with eval scorecards, agentic benchmarks, and regression gates that reject candidates which break tasks the baseline solved.

Run, Measure, Optimize
Govern

Control permissions, sandbox policy, budgets, credentials, approvals, and delivery gates with explicit, reviewable rules.

Policies & Safety
Optimize

Improve model routes, harnesses, and skills through staged candidates, held-out evaluation, recorded negative evidence, and explicit human adoption.

Optimization Story

Main Capabilities¶

Harness specification

Write a harness.yaml that pins runtime, model policy, tools, memory, search, sandbox, approvals, and workflow. Validate it with harness doctor, commit it, and run the same contract anywhere.

Bring Your Own Harness
Harness independence

Keep the agent loop inspectable and versioned in your repo. SuperQode lets teams measure, change, and improve the harness itself instead of depending on a locked product harness.

What Is Harness Engineering
Model routing

Use Open Models or closed models, local endpoints or remote providers, small utility models or large coding models. The harness remains the portable configuration layer.

Runtime Backends
Local first Open Model support

Detect local engines, probe real context windows, generate starter harnesses, smoke test readiness, repair weak tool calls, and benchmark local candidates.

Local Agentic Coding
Local dynamic workflows with RLM

Use local recursive language-model runs for large logs, traces, diffs, and repo-slice audits. context_handle, spawn_harness, and bounded dynamic workflow scripts keep evidence outside the prompt while preserving replayable lineage.

Local Recursive Dynamic Coding
Evaluation and optimization

Use harness tests, eval scorecards, local route optimization, harness optimization, and skill optimization. Stage changes and adopt them only after regression gates pass.

Optimization Story
Terminal-first Code Factory

Move from a repo-owned HarnessSpec to durable role-aware WorkOrders, isolated workers, terminal operations, verified delivery, and evidence-backed harness improvement.

Code Factory
Local code intelligence

Provide bounded repository context through local code search, multi repo search, semantic search, offline indexes, and post edit verification.

Multi-Repo Search & Edit Safety
Airplane Mode

Prepare a strict offline harness with local repositories, local model servers, local indexes, cached metadata, and network tools removed.

Airplane Mode
Configurable memory

Local first agent memory supports remember, search, forget, and export operations. Connect provider neutral memory systems when needed.

Memory & Learning
Policy controlled tools

Bounded reads, shell sessions, patch edits, vision attachments, MCP tools, web tools, and verification hooks are gated by explicit permissions and sandbox policy.

Tools Catalog
Runtime and protocol integrations

Connect to existing runtimes, SDKs, MCP tools, ACP agents, and A2A workflows while keeping the harness as the portable contract.

Connection Methods and Vendors

Feature Reference Map¶

Every major product surface has a dedicated reference page. Start with the area you are changing, then use the CLI reference when you need exact flags.

Area	Documentation
Product capability coverage	Product Capability Reference
CLI commands	CLI Reference
TUI commands	TUI Reference
Harness specs, workflows, evals, and events	Harness System
Runtime backends and SDK adapters	Runtime Backends
Providers, model catalog, and connection profiles	Models & Providers
Local and Open Model workflows	Local Agentic Coding
Tools, search, MCP, and permissions	Tools Catalog
Safety, sandboxing, and approvals	Safety & Permissions
Sessions, sharing, memory, and logging	Session Management
Code Factory, WorkOrders, workers, and delivery gates	Building a Code Factory with SuperQode
Omnigent similarities, differences, and interoperability	How SuperQode Relates to Omnigent
Plugins, skills, and optimization	Plugin Authoring
Automation, channels, MCP, ACP, and A2A	Advanced Workflows
Environment variables and YAML config	Configuration

The release checks include a CLI documentation coverage test so new command groups are not added without a reference page.

Capability demonstrations¶

Interactive TUIHeadlessHarness contractCI quality gate

:connect local          # pick a local model server
:plan fix the tests     # review the plan before tools run
:plan approve           # execute it
:context                # check the detected context window
:local optimize         # benchmark candidates and generate role routes

Type while the agent works and your message steers the current run between tool calls.

superqode -p --mode json "summarize the architecture" | jq .success
superqode -p --resume 4f2a "continue where we left off"
superqode sessions export 4f2a --format html -o run.html

# harness.yaml: the portable run contract
name: my-coder
flavor: coding
runtime:
  backend: builtin
model_policy:
  primary: ollama/gemma4
  tool_call_format: prompt    # for models without a native tool head
execution_policy:
  sandbox: docker
  approval_profile: ask

superqode harness run --spec harness.yaml --prompt "make the smallest safe fix"
superqode harness events <run-id>

superqode -p \
  --sandbox git-worktree \
  --rubric "the full test suite passes; the diff is minimal" \
  --output-schema fix-report.schema.json \
  "find one failing test and fix it properly" > report.json

jq -e '.schema_valid and .success' report.json

How a run works¶

1. SPEC       Choose coding, no-tool, or custom harness behavior
2. MODEL      Apply model policy, local hints, fallback rules, and prompt profile
3. RUNTIME    Select builtin, OpenAI Agents, ADK, Codex SDK, Claude Agent SDK, DeepAgents, or PydanticAI
4. TOOLS      Attach repository tools, MCP tools, validation hooks, or no tools
5. SESSION    Persist history, stream events, compact context, store runs, resume work
6. WORKFLOW   Run single, chain, parallel, router, orchestrator, or evaluator-optimizer flows
7. RESULT     Return text, diffs, typed data, events, and validation state

Every stage is observable: superqode harness events <run-id> shows the normalized event graph regardless of which runtime executed the work.