# SuperQode

> Open-source harness layer for coding agents to discover, build, run, evaluate and optimize harnesses across ACP, A2A, MCP and UHP.

SuperQode is an open-source, terminal-first harness layer for coding agents, built by Superagentic AI under the Apache 2.0 license. It lets teams connect the coding agents and models they already use, or define their own harness, and run them through one inspectable contract. A public beta native macOS app (0.1.7, Apple Silicon, macOS 14+) is available alongside a Python CLI/TUI.

## What It Is

SuperQode treats the harness, the loop around a model that decides which tools it can call, what it remembers, what it may change and how its work is verified, as a repository-owned artifact. A portable HarnessSpec in YAML controls runtime, model policy, tools, memory, search, sandbox, approvals, workflow and evidence. Users can connect vendor plans, ACP agents, bring-your-own-key providers or local models, then work from the TUI, the Mac app or headless CLI runs.

## Harness Hub and Native Harnesses

The Harness Hub is a browsable catalog, in the terminal and on the web, of native harnesses, vendor agents, ACP registry agents, optional runtimes and model presets, with openness and licence information per entry. Native harnesses include Core, RLM (a recursive harness that works through a persistent Python environment), PiPy, Workbench, SystemOne and CodeGem. CodeGem is a six-tool Python harness (read, write, edit, search, python, bash) for Gemini through the Google API or local Gemma, with optional local EmbeddingGemma semantic search.

## Interoperability Over A2A, UHP and MCP

SuperQode can drive remote agents and also be called as one. It can serve a HarnessSpec as an Agent2Agent agent with a published Agent Card, and the public agent at a2a.superqode.dev offers a harness-shortlist skill. The site reports passing all MUST and MAY requirements in the A2A Technology Compatibility Kit (96.4% overall). It can also serve and drive harnesses over the Unified Harness Protocol, and the site reports 40 of 40 conformance checks with no skips.

## Evaluation, Optimization and Records

Harnesses can be tested and evaluated against repository tasks, comparing baseline and candidate variants. Optimization (GEPA Omni, HarnessBench, SkillOpt) produces reviewable candidates that are promoted only explicitly, and never edits the live spec. SystemOne uses Jev for bounded decisions such as tool routing and offers a Tune workflow that learns from reviewed examples. The `sq gauge` command emits Agent Quality Records, built on the open SuperGauge specification, that can gate CI. WorkOrders run durable multi-harness tasks with isolated worktrees and a human delivery decision.

## Setup Path

Install the Mac app from the DMG, or run the install script or `uv tool install superqode` (Python 3.12+). Then open a repository, run `superqode`, and use `:connect` to attach an agent, provider key or local model. Agent tools execute with the user's host permissions, so reviewing changes is advised.

## Features
- Portable HarnessSpec YAML for tools, permissions, model policy, memory and workflows
- Harness Hub catalog of 83 harnesses including 39 ACP agents
- Interactive TUI, headless CLI and native macOS app
- Connect vendor plans, ACP agents, BYOK providers or local models
- CodeGem harness for Gemini and local Gemma with EmbeddingGemma search
- Native recursive RLM harness
- Serve and call harnesses over A2A and UHP
- SystemOne with Jev tool routing and Tune decision learning
- Harness evaluation, GEPA Omni optimization and gated promotion
- Agent Quality Records via sq gauge for CI gating
- WorkOrders with isolated worktrees and delivery approval
- Sandboxed execution via local OS, Docker, Podman, E2B, Daytona, Modal, Vercel
- Airplane mode offline operation

## Integrations
ACP, A2A, MCP, UHP, Codex, Claude, GitHub Copilot, Grok, OpenCode, Cline, OpenHands, Gemini, Ollama, LM Studio, MLX, vLLM, SGLang, llama.cpp, Docker, Podman, E2B, Daytona, Modal, Vercel, mem0, cognee, supermemory, Google ADK, PydanticAI, OpenAI Agents SDK

## Platforms
MACOS, LINUX, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
0.1.7

## Links
- Website: https://superqode.dev
- Documentation: https://docs.superqode.dev/
- Repository: https://github.com/SuperagenticAI/superqode
- EveryDev.ai: https://www.everydev.ai/tools/superqode