superqode 0.2.32

The Agent Engineering framework for your code

SuperQode

The Agent Engineering Framework for Your Code
Engineer reliable coding agents with portable harnesses, context, memory, tools, and control loops. Use any agent or model, from terminal sessions to software factories.

Code engineering for the agent-driven world

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

Documentation • Report an issue • Discussions

---

What is SuperQode?

SuperQode is the open-source, terminal-first Agent Engineering framework for your code. It provides the lifecycle for building, running, evaluating, governing, and optimizing reliable coding agents and software factories.

Agent Engineering is the discipline of designing, building, evaluating, governing, and operating agents as reliable systems. SuperQode applies that discipline to the complete system that produces code, from one coding agent working on a codebase to a multi-agent software factory.

Harness engineering is one discipline within Agent Engineering. The harness is the software around the model that determines what it can see, which tools it can call, how it remembers, and how its work is checked. SuperQode treats that harness as a repository-owned engineering artifact instead of a hidden part of a closed agent product.

Many coding products ship a finished harness that cannot be inspected or moved between runtimes. Open models often ship without a complete coding harness. SuperQode provides a portable HarnessSpec for model routing, tools, memory, context, search, approvals, sandboxing, workflows, evaluation, and optimization. The specification lives in the repository and remains under the team's control.

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 turning SuperQode into a separate web or mobile platform.

SuperQode brings five connected Agent Engineering capabilities to a harness you own:

• Build it as a versioned file, with a wizard, model-family templates, and a plain-English explain.
• Run it across runtimes, providers, MCP, ACP, and A2A without changing the contract.
• Evaluate it with scorecards, agentic benchmarks, and regression gates before you trust it.
• Govern it with explicit permissions, sandbox policy, budgets, credentials, approvals, and delivery gates.
• Optimize it with staged candidates a human adopts, so a failure gets fixed once instead of retried.

SuperQode provides harness independence by keeping the agent configuration inspectable, versioned, measurable, and portable across local and hosted models.

Run superqode for the terminal workbench, then :local init to detect your hardware, generate a local first starter harness, and run a readiness smoke test. The CLI mirrors the same path with superqode local init --repo .. Run superqode local optimize to benchmark candidates and generate role specific routing for planner, implementer, reviewer, and utility agents.

The TUI and CLI apply consistent tool policies, event logging, and session management across supported agent types. A portable HarnessSpec can be executed locally, on a team host, through remote runtimes, or in CI while allowing independent changes to runtimes, models, memory, search, and tools.

For work that must reliably finish across several harnesses, use a durable WorkOrder. A WorkOrder adds investigator, implementer, synthesizer, reviewer and tester roles, bounded parallel workers, isolated task worktrees, deterministic patch integration, leases and crash recovery, acceptance commands, typed evidence, and an explicit human decision without requiring a web control plane:

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 watch work_...
sq work check work_...
sq work prepare work_...
sq work diff work_...
sq work approve work_... --actor maintainer
sq work merge work_... --actor maintainer --cleanup

This is the durable execution layer inside SuperQode's terminal-first Software Factory. Read the complete Software Factory guide for the product architecture and end-to-end builder workflow, or How SuperQode Relates to Omnigent for shared ideas, different priorities, remote access, and interoperability.

For controlled unattended work, sq policy init enables layered contextual policy, secret-filtered shells, strict network destinations, and named host-bound HTTP credentials. Use sq harness bench to publish a reproducible same-model harness comparison, then deliver an audited improvement through sq harness promote stage, canary, activate, and rollback.

cd your-project && superqode

Core Concepts

SuperQode separates agent systems into interchangeable pieces: the harness controls runtime, tools, sandbox, memory, search, workflow, approvals, and model policy; the runtime executes the work; tools expose file, search, edit, shell, MCP, and verification capabilities under policy; and model policy controls routing, temperature, reasoning, context, and iteration limits. Change any piece without rewriting the rest.

Quick Start

Installation

Primary (Recommended)

# Install with uv
uv tool install superqode

# Or run without installing
uvx superqode

This installs the latest SuperQode release from PyPI.

SuperQode uses uv for installs, development, and release checks. If uv is new to you, start with the official uv documentation before installing extras or working from source.

Installed releases provide both superqode and the shorter sq command. They are equivalent, so humans can use commands such as sq, sq harness list, and sq --harness workbench; documentation, scripts, and agents can keep using the explicit superqode name.

Run SuperQode

Interactive TUI

cd your-project
superqode

Inside the TUI, the local-first MVP path is:

:local init          # detect hardware, generate superqode.local.yaml, run smoke when possible
:local labs          # browse trusted models.dev Labs recommendations
:connect local       # pick Ollama, LM Studio, MLX, DS4, vLLM, or SGLang
:harness superqode.local.yaml

Local model safety: Local inference can use substantial CPU, GPU, memory, battery, and disk bandwidth. Do not run local models on hardware that cannot safely support them. Monitor temperature, memory pressure, fan noise, battery, and system responsiveness. Use smaller models, lower context, or hosted/BYOK providers when your machine is constrained. SuperQode provides hardware checks and guardrails, but you are responsible for running local models responsibly on your own hardware.

superqode.yaml and superqode.local.yaml have different jobs. superqode.yaml is project configuration: provider hints, endpoints, MCP servers, memory providers, aliases, and default connection settings. superqode.local.yaml is a HarnessSpec: the repeatable run contract for runtime, model policy, tools, sandbox, approvals, checks, workflow, and events. Generate project config with superqode config init; generate a harness with :local init, superqode local init --repo ., or superqode harness init ....

File	Purpose	Created by
superqode.yaml	Project configuration: providers, endpoints, MCP, memory, defaults	superqode config init or :init
harness.yaml	Portable agent run contract	:harness wizard, superqode harness wizard, or superqode harness init ...
superqode.local.yaml	Local-first HarnessSpec generated for this machine	:local init or superqode local init --repo .
superqode.airplane.yaml	Strict no-network HarnessSpec for offline local work	:local airplane prepare or superqode local airplane prepare

Headless coding harness

cd your-project
superqode --print "inspect this repository and suggest the smallest next step"

SuperQode starts with the built-in core harness: a compact prompt and exactly four model-facing tools, read, write, edit, and bash. The former tool-rich native behavior remains available as workbench.

superqode harness list
superqode harness show core
superqode --harness workbench --print "inspect this repository"
superqode harness use workbench   # persist the project default in superqode.yaml

In the TUI, enter :harness or :harness switch to open the interactive Harness Switcher. Use the arrow keys and Enter to continue the current session with the selected harness, or press F to fork the session before switching. Direct commands such as :harness switch workbench remain available. Named harnesses, built-in templates, and HarnessSpec files use the same --harness option. Use :harness customize <name> to create a project-owned editable copy. Press A in the switcher when you need pinned compatibility or specialized presets.

The conversation session is durable and the active harness is replaceable. Switching harnesses keeps the same session ID and replays the stored context through the selected harness. Use --fork when the new harness should work on an independent copy of the conversation.

:harness switch workbench
:harness switch kimi-coding
:harness switch workbench --fork
:sessions switch

The same operation is available for a headless CLI turn:

superqode --print --resume SESSION_ID --harness workbench "continue the task"
superqode --print --fork SESSION_ID --harness kimi-coding "try another approach"

The harness catalog reports runtime mode, readiness, continuity, and model route. The session picker shows the current harness for every saved session. Selecting a session restores its latest harness, model, and conversation history. Vendor-owned thread stores remain accessible through runtime commands such as :codex sessions and :claude sessions.

Your First Harness Run

A harness is the repeatable contract for how an agent run behaves. In the TUI, create and load your first harness without writing YAML:

:connect local
:harness wizard

Press Enter through the defaults for a runnable local coding harness, choose an output file, and answer yes when asked whether to load it. If harness.yaml already exists, the wizard uses the next available path such as harness-2.yaml.

For the CLI path, start with the interactive wizard or the default coding template:

cd your-project
superqode harness wizard
superqode harness explain --spec harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "summarize the architecture"

Template shortcut:

cd your-project
superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "summarize the architecture"

Prefer to start from a complete file? See examples/harnesses for ready-to-run specs covering builtin, no-tool, PydanticAI, DeepAgents, RLM Code, OpenAI Agents SDK, Google ADK, Gemma4, and DS4.

After a run, inspect what happened:

superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness graph <run-id> --json

Harness Protocol v1 provides one versioned session and evidence contract for native Core, direct Python harnesses, and ACP agents. Inspect the reference adapters or run the deterministic offline conformance suite:

superqode harness protocol describe
superqode harness protocol conformance

An independently installed Python harness needs only one async function and one entry point:

[project.entry-points."superqode.harnesses"]
my-harness = "my_package:run"

pip install -e .
superqode harness list
superqode harness run my-harness "review this diff"
superqode harness protocol conformance my-harness

See Harness Protocol v1 for the Python API, capability boundaries, canonical events, and current limits.

Use doctor before sharing a harness with a team. It checks backend availability, spec compatibility, sandbox policy, event-store readiness, approval support, MCP config paths, and rich event graph support.

Common Harness Choices

Goal	Start with
Let SuperQode edit, search, and run shell commands under policy	superqode harness init app --template coding
Evaluate model capability without tools or repository access	superqode harness init reasoner --template no-tool
Start from an Open Model family pack	superqode harness list-templates
Generate a local first harness for this machine	superqode local init --repo .

Optional Runtime Backends

Install only the runtimes you need:

uv tool install "superqode[adk]"
uv tool install "superqode[openai-agents]"
uv tool install "superqode[codex-sdk]"
uv tool install "superqode[claude-agent-sdk]"
uv tool install "superqode[antigravity-sdk]"
uv tool install "superqode[deepagents]"
uv tool install "superqode[pydanticai]"
uv tool install "superqode[rlm-code]"

Install the three vendor SDK runtimes together only when you need all of them:

uv tool install "superqode[vendor-sdks]"

The default installation stays lightweight. The bundle includes the Codex, Claude Agent, and Antigravity SDK runtimes. It does not install the Grok or Antigravity subscription CLIs, which retain their own installers and login flows. Run superqode runtime setup or :runtime setup for environment-aware commands and authentication steps.

Then select a backend in a spec or at run time:

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 codex-sdk --prompt "summarize this repository"
superqode harness run --spec examples/harnesses/rlm-code-lid.yaml --provider ollama --model qwen3:8b --prompt "map this repository with evidence"

Key Features

• Harness specification: One portable spec controls runtime, model policy, tools, memory, search, sandbox, approvals, workflow, and output.
• Harness independence: Inspect, version, measure, and improve the agent loop as your own repository artifact instead of depending on a locked product harness.
• Harness Protocol v1: Run native Core, package-style Python harnesses, and ACP agents through one versioned lifecycle and durable evidence envelope without pretending their optional capabilities are identical.
• Extensible minimal Core: Start with only read, write, edit, and bash, then opt into trusted Python packages or project plugins that contribute tools, commands, skills, context, lifecycle hooks, permission rules, and providers.
• Model routing: Use Open Models or closed models, local endpoints or remote providers, small utility models or large coding models.
• Local first Open Model support: Detect local engines, probe context windows, generate starter harnesses, run smoke checks, and benchmark local candidates.
• Local dynamic workflows with RLM: Run recursive local-model analysis over large logs, traces, diffs, and repo slices with context_handle, spawn_harness, and bounded dynamic workflow scripts.
• First-class RLM Code backend: Run RLM Code v0.1.11+ reference, repo_evidence, or lid profiles through HarnessSpec and Harness Protocol while preserving root/submodel usage, exposure metrics, and native JSONL trajectories.
• Measure and optimize: Use harness tests, eval scorecards, local route optimization, harness optimization, and skill optimization with regression gates.
• Local code intelligence: Use bounded reads, local code search, multi repo search, semantic search, offline indexes, and post edit verification.
• Configurable memory: Keep local memory by default, then connect provider neutral memory systems when needed.
• Pluggable runtimes: Run the same harness on the builtin engine, ADK, OpenAI Agents SDK, Codex SDK, Claude Agent SDK, DeepAgents, PydanticAI, or RLM Code.
• Policy and safety: Gate file access, shell commands, network access, approvals, sandboxing, plugins, MCP, and project trust through explicit policy.
• Headless and CI ready: Run coding tasks, provider checks, evals, schema validated outputs, event exports, and change summaries from scripts.

Built for Open Models and local execution

SuperQode is tuned for local and Open Models, where context, tool calling, memory, and search usually decide whether an agent works:

• Auto context management: Detects each local model's real loaded context window and compacts before overflow. Inspect or pin it with :context.
• Context economy tools: Bounded reads, line numbered output, continue hints, output spill files, stale output pruning, and compact previews for long commands.
• Local search stack: Register repos with :workspace add, search across repos with ripgrep, add local code search, and enable semantic search when needed.
• Airplane Mode: Prepare a strict offline harness with local repositories, local model servers, local indexes, cached metadata, and network tools removed.
• Post edit verification: Feed fast per file checks back into the agent so it can correct mistakes before moving on.
• Resilient tool calls: Repair malformed tool calls, return corrective argument feedback, and block repeated no progress loops.
• Model aware edit formats: Support string replacement edits, unified diffs, patch envelopes, shell sessions, and vision attachments where the selected model supports them.
• Safe parallelism: Run read only tool batches concurrently while preserving strict order for edits, writes, and shell commands.
• Harness over MCP: Expose your HarnessSpec workflows as MCP tools for any MCP client, alongside A2A and ACP servers.

Developer Workflows

Use SuperQode as a daily coding-agent harness from the TUI or CLI:

superqode --tui
superqode --print "fix the failing test and summarize the change"
superqode --runtime codex-sdk --print "review this repo"
superqode --connect claude --print "summarize the last change"

Inside the TUI, start with :help and these commands:

:connect codex        # Codex SDK with local Codex login
:connect claude       # Claude Agent SDK with ANTHROPIC_API_KEY
:connect antigravity  # signed-in Antigravity CLI (Google OAuth/keyring)
:connect byok google  # Google API key path
:connect grok         # Grok Build, xAI's own agent over ACP
:grok api             # SuperQode core/workbench harness on the same subscription
:connect byok         # hosted provider/API-key path
:connect local        # local model provider
:connect acp          # installed and featured ACP coding agents
:connect acp all      # complete official registry plus SuperQode adapters
:connect acp refresh  # refresh the cached official ACP Registry
:tree                 # saved session branches
:share create         # portable superqode-share-v1 artifact
:export markdown      # copyable transcript export
:trust doctor         # project-local plugins/MCP/hooks audit
:plugins doctor       # non-executing plugin manifest validation
:plan fix the tests   # planning-only review before tools run
:plan approve         # execute the last planned request
:plan edit ...        # adjust the pending request before execution
:memory providers     # local and SpecMem-aware memory status
:memory remember ...  # explicit local project memory
:vim on               # optional Vim-like modal terminal navigation
:vim tutor            # modes and navigation reference

The optional Vim layer provides Normal, Insert, Command, and Search states for navigating conversations, panes, pickers, sessions, and agent output without leaving the keyboard. See Vim-Like Terminal Navigation.

CLI equivalents:

superqode sessions tree
superqode share create <session-id>
superqode share import <artifact.superqode-share.json> --session-id imported
superqode trust doctor
superqode trust yes
superqode plugins add ./my-plugin
superqode plugins doctor
superqode plugins doctor --runtime  # trust-gated import and activation check
superqode memory remember "Use pnpm in this repo; do not use npm" --kind preference
superqode memory search "package manager"
superqode memory providers  # local default; optional mem0/cognee/supermemory disabled until configured

Find free/local inference paths and current zero-price model routes:

superqode providers scan-free
superqode providers scan-free --live --source openrouter --limit 20

Inside the TUI, use :providers free for setup hints or :providers free --live openrouter for live zero-price model routes.

See Developer Workflows for the full command set.

How It Works

HARNESS LIFECYCLE
━━━━━━━━━━━━━━━━━
1. SPEC       Choose coding, no-tool, local-model, or custom harness behavior
2. MODEL      Resolve policy for Gemma4, DS4, hosted models, or model-only runs
3. RUNTIME    Run on builtin, OpenAI Agents, Google ADK, DeepAgents, or another backend
4. TOOLS      Attach file, search, edit, shell, MCP, or no tools
5. SESSION    Stream events, persist history, compact context, and store runs
6. OUTPUT     Return text, typed data, workflow results, and validation state

The default coding harness supports repository operations. The no-tool harness evaluates model capability without repository or tool access. Optional runtimes allow teams to use an existing agent framework without replacing the SuperQode harness contract.

Rich Runtime Observability

SuperQode normalizes runtime-specific streams into one harness event graph:

Backend	Rich graph events
builtin	Model requests, model deltas, tool calls, tool results, approval pauses, final results
pydanticai	Model deltas, tool calls, tool results, final results, approval pauses
openai-agents	Model deltas, tool calls, tool results, approval pauses, sandbox markers
codex-sdk	Model deltas, command output, patch updates, command/file-change results, turn completion
deepagents	Model deltas, tool calls, subagent activity, memory reads/writes, sandbox file/command events, final results
adk	Run and stream events with the same graph storage contract

This gives teams one way to debug runs even when they use different agent frameworks.

Documentation

For complete guides, configuration options, and API reference:

📚 View Full Documentation →

Highlights:

• Local Context & Compaction: context-window detection, adaptive compaction, :context
• Multi-Repo Search & Edit Safety: :workspace, cross-repo search, post-edit verification
• Harness System: HarnessSpec, checks, and exposing harnesses over MCP

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines. Development uses uv for dependency management and command execution.

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 for developers who care about code quality.