SuperQode¶

Your Portable Local Agentic Coding Harness

Turn open models into serious coding agents. Your harness, your models, your memory. Built for Local Agentic Coding, connected to everything else through BYOK, ACP, agent SDKs, MCP, and A2A.

Get Started Inside the Agent Loop View on GitHub

Up and running in 60 seconds¶

uv tool install superqode    # or: pip install superqode
cd your-project
superqode

That is the full interactive TUI. For scripts and CI, run one task and print the answer:

superqode --print "inspect this repository and suggest the smallest safe cleanup"

Why teams pick SuperQode¶

Built-in harness, or define your own

Start coding immediately with the built-in harness, or write a harness.yaml that pins runtime, model policy, tools, sandbox, approvals, and workflow. Validate it with harness doctor, commit it, and run the same contract anywhere.

Configuration vs Harness
Local Agentic Coding, first-class

superqode local doctor recommends the right engine and model for your machine and generates a tuned harness. superqode local optimize benchmarks local/open candidates and generates per-role routing for planner, implementer, reviewer, and utility agents. Underneath: live context-window detection, adaptive compaction, model policy packs, tool-call repair, doom-loop guards, and prompt-based tool calling for models without a tool head.

Local Agentic Coding
35+ policy-controlled tools

Bounded reads, spill-to-disk shell output, interactive PTY sessions, patch-envelope edits, vision attachments, and web access. Every tool gated by permissions, exec-policy rules, and sandboxing.

Tools Catalog
All three protocols

MCP client and server, ACP agent connections, and A2A serving and calling, in one product. Expose your harnesses as MCP tools with a single command.

Serve Commands
Pluggable runtimes

Run the same harness on the builtin engine, OpenAI Agents SDK, Google ADK, Codex SDK, Claude Agent SDK, DeepAgents, or PydanticAI. Swap engines without rewriting workflows.

Runtime Backends
Multi-agent, supervised

One-shot sub-agents, long-lived peer agents you can steer mid-run, external A2A agents, and rubric self-grading to hold unattended work to a standard.

Multi-Agent Workflows
Safety as policy, not hope

Declarative allow/deny/ask rules for shell commands, secret filtering for spawned processes, OS sandboxing, permission escalation with consent, and hard denies nothing can override.

Policies & Safety
Headless and CI-ready

JSON event output, schema-validated answers with automatic correction, rubric quality gates, session exports to Markdown, JSON, or shareable HTML, and disposable worktree isolation.

Headless & CI
Memory that stays yours

Local-first agent memory with explicit control: remember, search, forget, export. Plug in mem0, Cognee, Supermemory, or SpecMem when you want more, and opt in to the full loop: automatic capture of durable facts from completed runs, and automatic recall when they matter again.

Memory & Learning

See it work¶

Interactive TUIHeadlessHarness contractCI quality gate

:connect local          # pick a local model server
:plan fix the tests     # review the plan before tools run
:plan approve           # execute it
:context                # check the detected context window
:compare gpt-5.4 gemma4 # same prompt, two models, side by side

Type while the agent works and your message steers the current run between tool calls.

superqode -p --mode json "summarize the architecture" | jq .success
superqode -p --resume 4f2a "continue where we left off"
superqode sessions export 4f2a --format html -o run.html

# harness.yaml: the portable run contract
name: my-coder
flavor: coding
runtime:
  backend: builtin
model_policy:
  primary: ollama/gemma4
  tool_call_format: prompt    # for models without a native tool head
execution_policy:
  sandbox: local
  approval_profile: ask

superqode harness run --spec harness.yaml --prompt "make the smallest safe fix"
superqode harness events <run-id>

superqode -p \
  --sandbox git-worktree \
  --rubric "the full test suite passes; the diff is minimal" \
  --output-schema fix-report.schema.json \
  "find one failing test and fix it properly" > report.json

jq -e '.schema_valid and .success' report.json

How a run works¶

1. SPEC       Choose coding, no-tool, or custom harness behavior
2. MODEL      Apply model policy, local hints, fallback rules, and prompt profile
3. RUNTIME    Select builtin, OpenAI Agents, ADK, Codex SDK, Claude Agent SDK, DeepAgents, or PydanticAI
4. TOOLS      Attach repository tools, MCP tools, validation hooks, or no tools
5. SESSION    Persist history, stream events, compact context, store runs, resume work
6. WORKFLOW   Run single, chain, parallel, router, orchestrator, or evaluator-optimizer flows
7. RESULT     Return text, diffs, typed data, events, and validation state

Every stage is observable: superqode harness events <run-id> shows the normalized event graph regardless of which runtime executed the work.

Learn it in order¶

Each step builds on the previous one.

Install and run: Installation, then Your First Session
Connect your models: Providers for hosted APIs, Local Models for Ollama, LM Studio, MLX, vLLM, and DS4
Understand the engine: Inside the Agent Loop and the Tools Catalog
Make it yours: Harness System for portable run contracts, Policies & Safety for guardrails
Automate: Headless & CI for scripts, pipelines, and schema-validated output
Go further: Developer Workflows, Multi-Agent Workflows, Runtime Backends, Plugin Authoring