superqode 0.2.0b1

SuperQode: harness engineering framework for coding agents, optimized for local and open models

SuperQode

The harness engineering framework for coding agents, optimized for local and open models
Build your own coding harness. Measure it. Extend it. Optimize it. Use any model, open or closed, small or large, local or remote, without giving up control of the agent loop.

📚 Documentation • 🐛 Report Bug • 💬 Discussions

---

What is SuperQode?

SuperQode is a harness engineering framework for coding agents, optimized for local and open models. The harness is the software around the model that decides what it can see, which tools it can call, how it remembers, and how its work is checked. After prompt engineering and context engineering, the harness is the layer that now decides whether a coding agent is reliable.

Most coding products ship a finished harness you cannot see, tuned to keep you on one model. Open Models ship with no harness at all. SuperQode gives you one you own: model routing, tools, memory, context, search, approvals, sandboxing, workflows, evals, and optimization, written as a YAML artifact that lives in your repo.

You do four things with a harness you own:

• Build it as a versioned file, with a wizard, model-family templates, and a plain-English explain.
• Measure it with eval scorecards, agentic benchmarks, and regression gates before you trust it.
• Extend it across runtimes, providers, MCP, ACP, and A2A without changing the contract.
• Optimize it with staged candidates a human adopts, so a failure gets fixed once instead of retried.

Use SuperQode when you want harness independence: the freedom to inspect, version, measure, and improve the system that makes a model useful on your codebase, with any model you choose, open or closed, small or large, local or remote.

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.

One TUI and CLI, consistent tool policies, event logging, and session management across every agent type. Define your harness once as a portable spec. Swap runtimes, models, memory, search, or tools without changing your workflow. Run the same contract locally, on a team machine, through remote runtimes, or in CI.

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)

# Using uv (best performance)
uv tool install superqode

# Or run without installing
uvx superqode

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.

Run SuperQode

Interactive TUI (Explore)

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

Your First Harness Run

A harness is the repeatable contract for how an agent run behaves. Start with the default coding harness:

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

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
Bet on 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[deepagents]"
uv tool install "superqode[pydanticai]"

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"

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.
• 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.
• 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, or PydanticAI.
• 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 Code through ACP
:connect antigravity  # local Antigravity CLI handoff
:connect byok         # hosted provider/API-key path
:connect local        # local model provider
: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       # 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

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 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 keeps repository work practical. The no-tool harness lets you bet directly on model capability. Optional runtimes let teams bring their preferred 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

We welcome contributions! 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.