Metadata-Version: 2.4
Name: superqode
Version: 0.2.97
Summary: The harness layer for coding agents
Author-email: Shashi Jagtap <info@super-agentic.ai>
Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://super-agentic.ai/superqode/
Project-URL: Repository, https://github.com/SuperagenticAI/superqode
Project-URL: Documentation, https://superagenticai.github.io/superqode/
Project-URL: Issues, https://github.com/SuperagenticAI/superqode/issues
Project-URL: Changelog, https://github.com/SuperagenticAI/superqode/blob/main/CHANGELOG.md
Keywords: ai,agent-engineering,code-engineering,code-factory,harness-engineering,coding-agents,agent-harness,multi-agent,orchestration,evaluation,optimization,acp,mcp,automation,superqode
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: click>=8.0.0
Requires-Dist: litellm<1.92,>=1.83.14
Requires-Dist: agent-client-protocol<0.12,>=0.10.0
Requires-Dist: prompt_toolkit>=3.0.52
Requires-Dist: rich>=15.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: fastmcp==3.4.4
Requires-Dist: mcp<2,>=1.27.1
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: httpx-sse>=0.4.3
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: superopt>=0.1.1
Requires-Dist: prime-agent-python-client<0.3.0,>=0.2.0
Provides-Extra: hf
Requires-Dist: huggingface_hub[hf_xet]>=1.0.0; extra == "hf"
Provides-Extra: mlx
Requires-Dist: mlx-lm<0.32.0,>=0.31.0; python_version < "3.14" and extra == "mlx"
Requires-Dist: mlx-vlm<0.6.0,>=0.5.0; python_version < "3.14" and extra == "mlx"
Provides-Extra: monty
Requires-Dist: pydantic-monty>=0.0.21; extra == "monty"
Provides-Extra: semantic
Requires-Dist: cocoindex-code<0.3,>=0.2.35; extra == "semantic"
Provides-Extra: channels
Requires-Dist: websocket-client>=1.6.0; extra == "channels"
Provides-Extra: sandbox-e2b
Requires-Dist: e2b>=2.0.0; extra == "sandbox-e2b"
Provides-Extra: sandbox-modal
Requires-Dist: modal>=1.0.0; extra == "sandbox-modal"
Provides-Extra: sandbox-daytona
Requires-Dist: daytona>=0.1.0; extra == "sandbox-daytona"
Provides-Extra: sandbox-cloud
Requires-Dist: e2b>=2.0.0; extra == "sandbox-cloud"
Requires-Dist: modal>=1.0.0; extra == "sandbox-cloud"
Requires-Dist: daytona>=0.1.0; extra == "sandbox-cloud"
Provides-Extra: web
Requires-Dist: textual-serve>=1.1.3; extra == "web"
Provides-Extra: extras
Requires-Dist: exa-py>=1.0.0; extra == "extras"
Provides-Extra: a2a
Requires-Dist: a2a-sdk[fastapi,sqlite]<2.0.0,>=1.1.2; extra == "a2a"
Requires-Dist: fastapi>=0.115.0; extra == "a2a"
Requires-Dist: uvicorn>=0.32.0; extra == "a2a"
Provides-Extra: adk
Requires-Dist: google-adk<3.0,>=2.1.0; extra == "adk"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.17.4; extra == "openai-agents"
Requires-Dist: openai-agents[litellm]>=0.17.4; extra == "openai-agents"
Provides-Extra: codex-sdk
Requires-Dist: openai-codex<1.0.0,>=0.144.4; extra == "codex-sdk"
Provides-Extra: copilot-sdk
Requires-Dist: github-copilot-sdk<2.0.0,>=1.0.8; extra == "copilot-sdk"
Provides-Extra: claude-agent-sdk
Requires-Dist: claude-agent-sdk<0.3.0,>=0.2.9; extra == "claude-agent-sdk"
Provides-Extra: antigravity-sdk
Requires-Dist: google-antigravity<0.2.0,>=0.1.8; extra == "antigravity-sdk"
Requires-Dist: protobuf>=7.35.0; extra == "antigravity-sdk"
Provides-Extra: vendor-sdks
Requires-Dist: openai-codex<1.0.0,>=0.144.4; extra == "vendor-sdks"
Requires-Dist: github-copilot-sdk<2.0.0,>=1.0.8; extra == "vendor-sdks"
Requires-Dist: claude-agent-sdk<0.3.0,>=0.2.9; extra == "vendor-sdks"
Requires-Dist: google-antigravity<0.2.0,>=0.1.8; extra == "vendor-sdks"
Requires-Dist: protobuf>=7.35.0; extra == "vendor-sdks"
Provides-Extra: deepagents
Requires-Dist: deepagents<0.8.0,>=0.7.0; extra == "deepagents"
Provides-Extra: pydanticai
Requires-Dist: pydantic-ai<2.0.0,>=1.98.0; extra == "pydanticai"
Provides-Extra: pydanticai-logfire
Requires-Dist: pydantic-ai<2.0.0,>=1.98.0; extra == "pydanticai-logfire"
Requires-Dist: logfire>=4.0.0; extra == "pydanticai-logfire"
Provides-Extra: rlm-code
Requires-Dist: rlm-code[llm-all]<0.2.0,>=0.1.11; extra == "rlm-code"
Provides-Extra: tau
Requires-Dist: tau-ai<0.4.0,>=0.3.3; extra == "tau"
Provides-Extra: deepseek-harness
Requires-Dist: deepseek-harness-sdk<0.2.0,>=0.1.0rc6; ((sys_platform == "darwin" and platform_machine == "arm64") or (sys_platform == "linux" and platform_machine == "x86_64") or (sys_platform == "linux" and platform_machine == "aarch64")) and extra == "deepseek-harness"
Provides-Extra: mem0
Requires-Dist: mem0ai<3.0.0,>=2.0.4; extra == "mem0"
Provides-Extra: supermemory
Requires-Dist: supermemory<4.0.0,>=3.45.0; extra == "supermemory"
Provides-Extra: memory-providers
Requires-Dist: mem0ai<3.0.0,>=2.0.4; extra == "memory-providers"
Requires-Dist: supermemory<4.0.0,>=3.45.0; extra == "memory-providers"
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=6.1.1; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.9.6; extra == "dev"
Requires-Dist: mypy>=1.17.0; extra == "dev"
Requires-Dist: pre-commit>=4.1.0; extra == "dev"
Provides-Extra: testing
Requires-Dist: pytest>=8.3.5; extra == "testing"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "testing"
Requires-Dist: pytest-cov>=6.1.1; extra == "testing"
Requires-Dist: coverage>=7.0.0; extra == "testing"
Requires-Dist: bandit>=1.8.0; extra == "testing"
Requires-Dist: httpx>=0.28.1; extra == "testing"
Provides-Extra: linters
Requires-Dist: bandit>=1.8.0; extra == "linters"
Requires-Dist: pylint>=3.3.0; extra == "linters"
Requires-Dist: flake8>=7.1.0; extra == "linters"
Requires-Dist: safety>=3.0.0; extra == "linters"
Requires-Dist: pip-audit>=2.10.0; extra == "linters"
Provides-Extra: ui-testing
Requires-Dist: selenium>=4.27.0; extra == "ui-testing"
Requires-Dist: playwright>=1.49.0; extra == "ui-testing"
Provides-Extra: performance
Requires-Dist: locust>=2.33.0; extra == "performance"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.12.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "docs"
Provides-Extra: optimization
Requires-Dist: gepa>=0.1.1; extra == "optimization"
Provides-Extra: observability
Requires-Dist: arize-phoenix>=17.7.0; extra == "observability"
Requires-Dist: arize-phoenix-otel>=0.16.1; extra == "observability"
Requires-Dist: langsmith>=0.8.5; extra == "observability"
Requires-Dist: logfire>=4.33.0; extra == "observability"
Requires-Dist: mlflow>=3.14.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.39.1; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.39.1; extra == "observability"
Dynamic: license-file

<p align="center">
  <img src="assets/superqode-banner.png" alt="SuperQode" width="760">
</p>

<p align="center">
  <strong>The harness layer for coding agents.</strong><br>
  Discover, build, run, evaluate, and optimize coding-agent harnesses from one terminal.
</p>

<p align="center">
  <a href="https://pypi.org/project/superqode/"><img src="https://img.shields.io/pypi/v/superqode?style=flat-square&color=7c3aed&label=pypi" alt="PyPI"></a>
  <a href="https://pypi.org/project/superqode/"><img src="https://img.shields.io/pypi/pyversions/superqode?style=flat-square&color=3776ab" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green?style=flat-square" alt="License"></a>
  <a href="https://github.com/SuperagenticAI/superqode/stargazers"><img src="https://img.shields.io/github/stars/SuperagenticAI/superqode?style=flat-square&color=f59e0b" alt="Stars"></a>
  <a href="https://github.com/SuperagenticAI/superqode/discussions"><img src="https://img.shields.io/github/discussions/SuperagenticAI/superqode?style=flat-square" alt="Discussions"></a>
</p>

<p align="center">
  <a href="https://superagenticai.github.io/superqode/"><strong>Documentation</strong></a>
  &nbsp;·&nbsp;
  <a href="https://superagenticai.github.io/superqode/getting-started/quickstart/">Quick Start</a>
  &nbsp;·&nbsp;
  <a href="https://superagenticai.github.io/superqode/harness-hub/">Harness Hub</a>
  &nbsp;·&nbsp;
  <a href="https://super-agentic.ai/superqode/">Website</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/SuperagenticAI/superqode/discussions">Discussions</a>
</p>

<p align="center">
  <img src="assets/superqode-hero.png" alt="The SuperQode terminal interface" width="880">
</p>

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

```bash
curl -fsSL https://super-agentic.ai/superqode.sh | sh
```

The installer pulls the latest release from PyPI into an isolated environment,
installs [uv](https://docs.astral.sh/uv/) when needed, and never uses `sudo`.
Already have uv? Run `uv tool install superqode` instead.

Open any repository and start:

```bash
cd your-project
superqode
```

Connect something, then work normally:

```text
:connect                # local models, ACP agents, BYOK, or a vendor plan
:connect codex          # or claude, copilot, grok, kimi-code, qwen-code
```

```text
Summarize this repository and identify the smallest safe improvement.
```

Prefer a single headless task?

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

```text
: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:

```bash
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:

```bash
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`](examples/harnesses). An
independently installed Python harness needs one async function and one entry
point to join the catalog:

```toml
[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:

```python
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](https://superagenticai.github.io/superqode/advanced/rlm/).

## Evaluate and Optimize

Treat the harness the way you treat the rest of your code: measure it, then gate
changes against repeatable tasks.

```bash
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:

```bash
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](docs/advanced/harness-optimization.md)
and [Harness Promotion](docs/advanced/harness-promotion.md).

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

```bash
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:

```bash
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](https://superagenticai.github.io/superqode/advanced/software-factory/).

## Harness Execution Model

```text
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 |

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

## Documentation

| Guide | What it covers |
| --- | --- |
| [Quick Start](https://superagenticai.github.io/superqode/getting-started/quickstart/) | Install, connect, and run your first task |
| [Harness Hub](https://superagenticai.github.io/superqode/harness-hub/) | Browsing, filtering, and the published catalog |
| [Connection Methods](docs/concepts/modes.md) | Local, ACP, BYOK, SDK, MCP, and A2A routes |
| [Developer Workflows](docs/developer-workflows.md) | The complete TUI and CLI command set |
| [Harness System](docs/advanced/harness-system.md) | HarnessSpec fields, runtimes, and policy |
| [Harness Protocol](docs/advanced/harness-protocol.md) | The versioned session and evidence contract |
| [Bring Your Own Harness](docs/getting-started/bring-your-own-harness.md) | Templates, wizard, and repository specs |

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

```bash
git clone https://github.com/SuperagenticAI/superqode
cd superqode
uv sync --extra dev --extra docs
uv run pytest
```

## License

[Apache-2.0](LICENSE), built by [Superagentic AI](https://super-agentic.ai/).
