Metadata-Version: 2.4
Name: superqode
Version: 0.2.40
Summary: Agent Engineering for your code factory
Author-email: Shashi Jagtap <info@super-agentic.ai>
Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
License-Expression: Apache-2.0
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
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: python-frontmatter>=1.1.0
Requires-Dist: superopt>=0.1.1
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.4; 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: 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<0.2.0,>=0.1.0b2; 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<0.2.0,>=0.1.0b2; 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.7.0,>=0.6.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: 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="820">
</p>

<h1 align="center">SuperQode</h1>

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

<h3 align="center">Agent engineering for your code factory.</h3>

<p align="center">
  Build your own coding-agent harnesses or connect the agents you already use.
</p>

<p align="center">Terminal-first · Any agent · Any model · Local or cloud · Open source</p>

<p align="center">
  <a href="https://pypi.org/project/superqode/"><img src="https://img.shields.io/pypi/v/superqode?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/superqode/"><img src="https://img.shields.io/pypi/pyversions/superqode?style=flat-square" alt="Python"></a>
  <a href="https://github.com/SuperagenticAI/superqode/blob/main/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" alt="Stars"></a>
  <a href="https://github.com/SuperagenticAI/superqode/network/members"><img src="https://img.shields.io/github/forks/SuperagenticAI/superqode?style=flat-square" alt="Forks"></a>
  <a href="https://github.com/SuperagenticAI/superqode/issues"><img src="https://img.shields.io/github/issues/SuperagenticAI/superqode?style=flat-square" alt="Issues"></a>
  <a href="https://github.com/SuperagenticAI/superqode/pulls"><img src="https://img.shields.io/github/issues-pr/SuperagenticAI/superqode?style=flat-square" alt="PRs"></a>
</p>

<h3 align="center">
  <a href="https://superagenticai.github.io/superqode/">📚 Read the Full Documentation →</a>
</h3>

<p align="center">
  <a href="https://superagenticai.github.io/superqode/getting-started/quickstart/"><strong>Quick Start</strong></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/SuperagenticAI/superqode/discussions">Discussions</a>
</p>

## What is SuperQode?

SuperQode is an open-source, terminal-first Agent Engineering framework for
building, connecting, orchestrating, evaluating, and governing coding-agent
harnesses across your repositories.

Run local or hosted models and the coding agents you already use through one
inspectable, portable HarnessSpec while keeping tools, policies, sessions, and
evidence under your control.

## Install

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

The installer gets the latest SuperQode release from PyPI in an isolated
environment, installs `uv` when needed, and does not use `sudo`.

Already use [uv](https://docs.astral.sh/uv/)?

```bash
uv tool install superqode
```

Then open any project:

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

`sq` is included as a shorter alias for every `superqode` command.

Uninstall anytime:

```bash
uv tool uninstall superqode
```

## Get Started

SuperQode opens a terminal workbench where you can choose a harness, connect a
model or coding agent, and inspect its work as it happens.

For a safe local-first setup:

```text
:local init       # detect hardware and create a starter harness
:connect local    # choose Ollama, LM Studio, MLX, DS4, llama.cpp, vLLM, or SGLang
:harness          # choose or switch the active harness
```

Or run a single headless task:

```bash
superqode --print "inspect this repository and suggest the smallest next step"
```

SuperQode starts with the compact `core` harness and its `read`, `write`, `edit`,
and `bash` tools. Select `workbench` when you want the broader native toolset:

```bash
superqode harness list
superqode --harness workbench --print "review this repository"
superqode harness use workbench
```

## What SuperQode Does

SuperQode makes the coding-agent harness an inspectable, repository-owned
engineering artifact. A portable `HarnessSpec` controls the runtime, model,
tools, memory, search, sandbox, approvals, workflow, checks, and event history.

That lets you:

- **Build** versioned harnesses with templates, a wizard, or plain YAML.
- **Connect** existing agents through native runtimes, ACP, MCP, and A2A.
- **Run** local or hosted models without changing the harness contract.
- **Observe** reasoning, tool activity, usage, progress, and durable sessions.
- **Evaluate** agent behavior with scorecards, benchmarks, and regression gates.
- **Govern** file, shell, network, credential, budget, and approval policies.
- **Optimize** model routes and harness candidates using recorded evidence.

<p align="center">
  <img src="assets/superqode-hero.png" alt="SuperQode Agent Engineering terminal workbench" width="920">
</p>

## Why Own the Harness?

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

## 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.
- **Model policy** controls routing, temperature, reasoning, context, and
  iteration limits.

You can change any one of these pieces without rewriting the rest.

## Choose a Harness

Open `:harness` in the TUI to select a built-in harness, a project
`HarnessSpec`, or an installed adapter. The same choices are available from the
CLI:

```bash
superqode harness list
superqode harness show core
superqode harness wizard
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "summarize the architecture"
```

Sessions remain durable when you switch harnesses. You can continue the same
conversation or fork it for an independent attempt:

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

Other optional runtimes include OpenAI Agents SDK, Google ADK, Codex SDK,
GitHub Copilot SDK, Claude Agent SDK, DeepAgents, PydanticAI, and RLM Code. See
[runtime setup](https://superagenticai.github.io/superqode/getting-started/installation/#optional-dependencies)
for installation commands and authentication guidance.

### Harness Sessions

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.

```bash
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 restores the latest harness, model, and conversation
history for each saved session. Vendor-owned thread stores remain available
through runtime commands such as `:codex sessions` and `:claude sessions`.

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

## Create Your Own Harness

Use the interactive wizard:

```bash
superqode harness wizard
superqode harness explain --spec harness.yaml
superqode harness doctor --spec harness.yaml
superqode harness run --spec harness.yaml --prompt "review this repository"
```

Or start from a template:

```bash
superqode harness init my-coder --template coding --output harness.yaml
```

Ready-to-run examples are in [`examples/harnesses`](examples/harnesses).
Independent Python harnesses can integrate through one async entry point and
the versioned [Harness Protocol](docs/advanced/harness-protocol.md).

After a run, inspect what happened:

```bash
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 protocol or
run the deterministic offline conformance suite:

```bash
superqode harness protocol describe
superqode harness protocol conformance
```

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

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

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

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

## Local and Open Model Support

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

- **Auto context management:** Detect the loaded context window and compact
  before overflow. Inspect or pin it with `:context`.
- **Context economy tools:** Use bounded reads, line-numbered output, continue
  hints, spill files, stale-output pruning, and compact previews.
- **Local search stack:** Register repositories with `:workspace add`, search
  across them with ripgrep, and enable semantic search when needed.
- **Airplane Mode:** Prepare a strict offline harness with local repositories,
  local models, cached metadata, and network tools removed.
- **Post-edit verification:** Feed fast per-file checks back to the agent so it
  can correct mistakes before moving on.
- **Resilient tool calls:** Repair malformed tool calls, return corrective
  feedback, and block repeated no-progress loops.
- **Model-aware edits:** Support string replacement, unified diffs, patch
  envelopes, shell sessions, and vision attachments where available.
- **Safe parallelism:** Run read-only tool batches concurrently while
  preserving strict order for edits, writes, and shell commands.

Local inference can use substantial CPU, GPU, memory, battery, and disk
bandwidth. Monitor your hardware and use smaller models, lower context, or
hosted providers when a machine is constrained.

### Project and Harness Configuration

`superqode.yaml` and `superqode.local.yaml` have different jobs:

| File | Purpose | Created by |
| --- | --- | --- |
| `superqode.yaml` | Project providers, endpoints, MCP, memory, aliases, and defaults | `superqode config init` or `:init` |
| `harness.yaml` | Portable agent run contract | `: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 work | `:local airplane prepare` |

## Code Factory Workflows

For work that must finish across multiple harnesses, use a durable WorkOrder:

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

WorkOrders provide bounded workers, isolated worktrees, crash recovery,
acceptance checks, typed evidence, and an explicit human delivery decision.
Read the [Code Factory guide](https://superagenticai.github.io/superqode/advanced/software-factory/)
for the complete workflow.

## Key Capabilities

- **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 a repository artifact.
- **Harness Protocol v1:** Run native Core, Python harnesses, and ACP agents
  through one versioned lifecycle and durable evidence envelope.
- **Extensible minimal Core:** Start with `read`, `write`, `edit`, and `bash`,
  then add trusted packages or project plugins.
- **Model routing:** Use Open Models or closed models, local endpoints or hosted
  providers, and role-specific routes.
- **Local-first support:** Detect engines, probe context windows, generate
  starter harnesses, run smoke checks, and benchmark candidates.
- **Dynamic RLM workflows:** Analyze large logs, traces, diffs, and repository
  slices with bounded recursive workflows.
- **Measure and optimize:** Use harness tests, scorecards, route optimization,
  skill optimization, and regression gates.
- **Local code intelligence:** Use bounded reads, multi-repository search,
  semantic indexes, and post-edit verification.
- **Configurable memory:** Keep memory local by default and connect
  provider-neutral memory systems when needed.
- **Pluggable runtimes:** Use the builtin engine, ADK, OpenAI Agents SDK, Codex
  SDK, GitHub Copilot SDK, Claude Agent SDK, DeepAgents, PydanticAI, or RLM
  Code while preserving the common contract each runtime supports.
- **Policy and safety:** Gate files, shell commands, network access, approvals,
  credentials, sandboxing, plugins, MCP, and project trust.
- **Headless and CI ready:** Run tasks, provider checks, evaluations,
  schema-validated outputs, event exports, and change summaries from scripts.

### Harnesses over MCP

Expose every HarnessSpec in a directory as an MCP tool:

```bash
superqode mcp --dir ./harnesses
superqode mcp --dir ./harnesses --http --port 8765
```

This is separate from adding external MCP tools to a harness through
`runtime.config.mcp_servers`. See the
[MCP command](docs/cli-reference/mcp-command.md) and
[MCP configuration](docs/configuration/mcp-config.md) guides.

## Developer Workflows

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

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

Inside the TUI, start with `:help`. Common commands include:

```text
:connect codex        # Codex SDK with local Codex login
:connect copilot      # GitHub Copilot SDK
:connect claude       # Claude Agent SDK
:connect antigravity  # signed-in Antigravity CLI
:connect byok         # hosted provider or API-key path
:connect local        # local model provider
:connect acp          # installed and featured ACP coding agents
:connect acp refresh  # refresh the cached official ACP Registry
:mcp                  # tool and resource server connections
:a2a                  # remote A2A agent connections
:tree                 # saved session branches
:share create         # portable session artifact
:export markdown      # transcript export
:trust doctor         # project plugin, MCP, and hook audit
:plugins doctor       # plugin manifest validation
:plan fix the tests   # planning-only review
:plan approve         # execute the approved plan
:memory providers     # memory provider status
:memory remember ...  # explicit project memory
:vim on               # optional Vim-like navigation
```

CLI equivalents:

```bash
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" --kind preference
superqode memory search "package manager"
superqode memory providers
```

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

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

See [Developer Workflows](docs/developer-workflows.md) for the complete command
set and [Connection Methods and Vendors](docs/concepts/modes.md) for the
supported local, ACP, BYOK, SDK, MCP, and A2A paths.

## Harness Execution Model

```text
HARNESS LIFECYCLE
1. SPEC       Choose coding, no-tool, local-model, or custom behavior
2. MODEL      Resolve local or hosted model policy
3. RUNTIME    Run on builtin, 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
```

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

## Runtime Observability

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

| Backend | Rich graph events |
| --- | --- |
| `builtin` | Model requests, deltas, tool calls, results, approvals, final output |
| `pydanticai` | Model deltas, tool calls, results, approval pauses, final output |
| `openai-agents` | Model deltas, tool calls, results, approvals, sandbox markers |
| `codex-sdk` | Model deltas, command output, patches, file changes, completion |
| `deepagents` | Model deltas, tools, subagents, memory, sandbox events, final output |
| `adk` | Run and stream events using the shared graph storage contract |

This gives teams one way to inspect and debug runs across different agent
frameworks.

## Documentation

The README is the quick path. Detailed setup, concepts, commands, providers,
and architecture live in the
[full documentation](https://superagenticai.github.io/superqode/).

- [Installation and optional runtimes](https://superagenticai.github.io/superqode/getting-started/installation/)
- [Developer workflows](docs/developer-workflows.md)
- [Connection methods and vendors](docs/concepts/modes.md)
- [Harness system](docs/advanced/harness-system.md)
- [Harness Protocol](docs/advanced/harness-protocol.md)
- [Local context and compaction](docs/advanced/local-context.md)
- [Multi-repository search and edit safety](docs/advanced/multi-repo-search.md)
- [MCP command](docs/cli-reference/mcp-command.md)

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

---

<p align="center">
  <strong>Build a coding-agent harness you can inspect, govern, and improve.</strong><br>
  <a href="https://superagenticai.github.io/superqode/"><strong>📚 Explore the Full Documentation →</strong></a>
  &nbsp;·&nbsp;
  <a href="https://superagenticai.github.io/superqode/getting-started/quickstart/"><strong>Get Started</strong></a>
</p>
