Metadata-Version: 2.4
Name: superqode
Version: 0.1.25
Summary: SuperQode: Multi-Agent Coding Agent Harness
Author-email: Shashi Jagtap <info@super-agentic.ai>
Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
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,coding-agents,multi-agent,orchestration,sdlc,automation,mcp,kubernetes,superqode
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
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.83.14
Requires-Dist: agent-client-protocol>=0.10.0
Requires-Dist: prompt_toolkit>=3.0.52
Requires-Dist: rich>=15.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: mcp>=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: codeoptix>=0.1.3
Requires-Dist: superopt>=0.1.1
Provides-Extra: mlx
Requires-Dist: mlx-lm<0.30.0,>=0.28.3; python_version < "3.14" and extra == "mlx"
Provides-Extra: monty
Requires-Dist: pydantic-monty>=0.0.17; extra == "monty"
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<2.0,>=1.33.0; extra == "adk"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.17.2; extra == "openai-agents"
Requires-Dist: openai-agents[litellm]>=0.17.2; extra == "openai-agents"
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: 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"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/SuperagenticAI/superqode/main/assets/superqode.png" alt="SuperQode TUI">
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/SuperagenticAI/superqode/main/assets/superqode-logo.png" alt="SuperQode Logo" width="200">
</p>

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

<p align="center">
  <strong>Production coding harness for local models, BYOK providers, and pluggable agent runtimes</strong><br>
  <em>Define the harness, choose the runtime, control the tools, and keep coding sessions readable.</em><br>
  <strong>Bring your own model, runtime, tools, and harness.</strong>
</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-AGPL--3.0-green?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <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>

<p align="center">
  <a href="https://superagenticai.github.io/superqode/">📚 Documentation</a> •
  <a href="https://github.com/SuperagenticAI/superqode/issues">🐛 Report Bug</a> •
  <a href="https://github.com/SuperagenticAI/superqode/discussions">💬 Discussions</a>
</p>

---

## What is SuperQode?

**SuperQode** is a production coding-agent harness for interactive development, local model workflows, BYOK providers, ACP coding agents, and tool-based repository work. It provides a TUI and CLI so developers can connect to the model or agent runtime they prefer, run file/search/edit/shell tools under policy, and get concise summaries of what changed.

The v2 direction is harness-first: SuperQode owns the kernel for sessions, tools, runtimes, model policies, sandboxing, typed outputs, workflow execution, validation, events, and backend adapters. Higher-level workflows can be built on top through A2A later without changing the core identity.

**Note (Enterprise):** Enterprise adds deeper automation, evaluation testing, and enterprise integrations.

## Core Concepts

SuperQode separates the pieces of an agent system so teams can change one piece without rewriting the rest.

| Concept | What it means in SuperQode |
|---------|----------------------------|
| **Harness** | The full contract for a run: flavor, model policy, tools, sandbox, workflow, output, events, and validation |
| **Runtime** | The engine that executes the harness, such as the native loop, Google ADK, OpenAI Agents SDK, or DeepAgents |
| **Flavor** | The kind of harness being run, such as tool-rich coding or model-only no-tool |
| **Tools** | Capabilities granted by policy, including file, search, edit, shell, MCP, todo, and validation tools |
| **Model policy** | The model-specific behavior for prompt level, temperature, reasoning, tool surface, history, and iteration limits |
| **Framework adapter** | A bridge that lets an external agent framework run behind the SuperQode harness contract |

The harness is the product contract. Runtimes and framework adapters are execution choices behind that contract.

## Demo Video

Watch the demo: [SuperQode Demo](https://www.youtube.com/watch?v=x2V323HgXRk)

<p align="center">
  <img src="https://raw.githubusercontent.com/SuperagenticAI/superqode/main/assets/super-qode-header.png" alt="SuperQode Banner">
</p>

## Quick Start

### Installation

**Primary (Recommended)**
```bash
# Using uv (best performance)
uv tool install superqode

# Or using pip
pip install superqode
```

**Alternate (No Python Required, SuperQode TUI Only)**
```bash
# Using Homebrew (macOS/Linux)
brew install SuperagenticAI/superqode/superqode

# Using Curl script
curl -fsSL https://super-agentic.ai/install.sh | bash
```

### Run SuperQode

**Interactive TUI (Explore)**
```bash
cd your-project
superqode
```

**Headless coding harness**
```bash
cd your-project
superqode --print "inspect this repository and suggest the smallest next step"
```



## Key Features

| Feature | Description |
|---------|-------------|
| **HarnessSpec** | Define coding, no-tool, local-model, and custom harness behavior with one declarative contract |
| **Harness kernel** | Run sessions with normalized events, run records, backend dispatch, typed outputs, and workflow execution |
| **Pluggable runtimes** | Swap the agent loop: SuperQode native, Google ADK, OpenAI Agents SDK, optional DeepAgents, or optional PydanticAI |
| **Developer TUI** | Interactive sessions with wrapped prompts, quiet streaming logs, compact tool activity, and readable change summaries |
| **Headless CLI** | Run coding tasks and provider checks from scripts or terminals |
| **Tool system** | File, search, edit, shell, todo, MCP, and optional Monty Python REPL tools |
| **Sandbox contract** | Use local sandbox policy for read, write, shell, command, grep, glob, and edit access |
| **Typed outputs** | Ask a harness run to return validated structured data using explicit result delimiters |
| **Workflow engine** | Run single, chain, parallel, router, orchestrator, and evaluator-optimizer workflows |
| **Model policies** | First-class Gemma4, DS4, coding, and no-tool policy profiles for local and hosted models |
| **Provider UX** | Provider doctor, model listing, guided local provider selection, and dynamic OpenCode free model discovery |
| **Harness flavors** | Tool-rich coding and model-only no-tool profiles, with room for Bring Your Own Harness specs |

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

## Documentation

For complete guides, configuration options, and API reference:

**[📚 View Full Documentation →](https://superagenticai.github.io/superqode/)**

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
git clone https://github.com/SuperagenticAI/superqode
cd superqode
uv pip install -e ".[dev]"
pytest
```

## License

[AGPL-3.0](LICENSE) - Built by [Superagentic AI](https://super-agentic.ai/) for developers who care about code quality.
