Harness Commands¶

The superqode harness command group creates, inspects, runs, and debugs harness specs. A harness spec is a portable YAML file that defines what a coding agent is allowed to do: model policy, tools, permissions, workflow, context, and observability.

Harness specs are separate from superqode.yaml. superqode.yaml configures the project environment. A harness file such as harness.yaml or superqode.local.yaml configures one repeatable agent run. You can keep many harness files in a repository and load the one you want with --harness or :harness.

New to harnesses? Start with Bring Your Own Harness for a guided walkthrough, then use this page as the command reference. The deep-dive on every spec field lives in Harness System.

superqode harness COMMAND [OPTIONS]

Command Summary¶

Selecting a Harness¶

The default core harness keeps model context small with a compact prompt and four tools: read, write, edit, and bash. Select workbench when a task benefits from the broader native search, patch, web, planning, and coordination toolset.

superqode harness list
superqode harness list --recommended
superqode harness current
superqode harness show core
superqode --harness workbench --print "fix the failing test"
superqode --harness kimi-coding --print "fix the failing test"
superqode harness use workbench

harness use stores the choice under superqode.harness in superqode.yaml. An explicit --harness name or HarnessSpec path takes precedence. In the TUI, the equivalent commands are :harness list and :harness use <name-or-path>. Entering :harness or :harness switch without a harness name opens the interactive Harness Switcher. Its default view starts at item 1 and groups the catalog in this order: SuperQode-managed harnesses, vendor coding agents, ACP agents, optional integrations, model and task presets, and project harnesses. Vendor integrations such as Codex, Claude, Kimi Code, Qwen Code, Copilot, Antigravity, and Grok display live readiness alongside installed, recent, and featured ACP agents and HarnessSpec entries such as Core, Workbench, Tau, Kimi, Qwen, and GLM. The ACP section ends with a Browse All row for the complete official registry. Use the arrow keys and Enter to connect or switch, F to fork a HarnessSpec session, I to inspect an entry, R to show only recommended HarnessSpecs, A to return to all entries, L to print the technical HarnessSpec catalog, and Escape to cancel. The CLI keeps superqode harness list limited to actual HarnessSpecs for scripting compatibility.

When a maintained Python integration such as Tau, Codex SDK, Claude Agent SDK, or Copilot SDK is missing, selecting it opens an installation confirmation inside the TUI. Press Enter to install and continue. SuperQode targets the exact Python interpreter running the TUI, then retries the selected harness without a restart. External CLI and local runtime installation remain manual.

The focused optional-integration view remains available through :connect other-harnesses.

Direct names use the same unified dispatch:

:harness switch codex
:harness switch claude
:harness switch kimi-code
:harness switch qwen-code
:harness switch acp:qwen
:harness switch acp:all
:harness switch tau
:harness switch kimi-coding

ACP names use the explicit acp:<name> namespace, which prevents an ACP adapter from colliding with a native vendor connector or HarnessSpec. Switching to an ACP agent starts its own runtime session. SuperQode queues up to 12 recent user and agent messages, bounded to 12,000 characters, and prepends that replay to the first prompt sent to the new agent. Status notices, errors, and setup output are excluded. The transition receipt reports how many messages were queued. Native ACP session resumption remains owned by each agent and is separate from this cross-agent replay.

Tau has a native SuperQode command family. Use :tau login <provider>/<model> to configure Tau and connect the route in one step, :tau use to reconnect its saved default route, and :tau status, :tau providers, :tau models, :tau model, :tau sessions, :tau logout, or :tau retry for ongoing management. Users do not need to open Tau's separate TUI or run Tau slash commands.

The list reports each harness runtime, readiness state, and continuity level. superqode harness current resolves the project default. During an interactive TUI session, :harness switch <name> either changes a HarnessSpec while retaining normalized history or connects the selected vendor agent through its native runtime. Add --fork when a HarnessSpec should receive an independent branch. Vendor agents retain their own native thread and session controls.

For non-interactive work, combine the top-level session and harness options:

superqode --print --resume SESSION_ID --harness workbench "continue the task"
superqode --print --fork SESSION_ID --harness kimi-coding "try another approach"

Built-in templates also appear in the selectable catalog and can be activated directly. list-templates remains available for authoring and compatibility. Maintained family presets such as kimi-coding track the validated stable model; versioned presets such as kimi-k3-coding stay pinned for reproducibility. In the TUI, :harness customize kimi-coding creates an editable project copy under .superqode/harnesses/.

Authoring¶

harness wizard¶

Build a harness.yaml interactively. Asks for a name, a model-family starting point, the provider/model, write/shell/network permissions, approval profile, tool-call format, and an optional multi-agent workflow, then writes the file and explains it in plain English. This is the recommended way to create a harness.

superqode harness wizard
superqode harness wizard --output team.yaml --force

harness init¶

Scaffold a spec from a built-in template, optionally applying a workflow preset. Also creates .agents/skills and .agents/roles directories.

superqode harness init my-coder --template qwen-coding
superqode harness init team --template coding --preset plan-implement-review
superqode harness init team --template coding --minimal

The qwen-coding, glm-coding, and glm52-coding templates reference a model-policy pack, so the matching tuning (temperature, parallel tools, history budget) is applied automatically. glm52-coding routes through the first-party Z.AI general API.

Specs can also compose from templates or relative files:

version: 1
name: team-coder
inherits: coding
model_policy:
  primary: ollama/qwen3-coder

Mappings are deep-merged, child scalar values override the base, and list fields replace the base list.

harness list-templates¶

List built-in templates with their flavor, runtime, and description.

superqode harness list-templates
superqode harness list-templates --json

harness list-backends¶

List the runtime backends a harness can target (builtin, ADK, OpenAI Agents, Codex SDK, Claude Agent SDK, DeepAgents, PydanticAI, and others).

superqode harness list-backends

harness import-omnigent¶

Convert an Omnigent agent.yaml into a SuperQode harness spec.

superqode harness import-omnigent agent.yaml --output harness.yaml

harness import-agent¶

Compile a concise SuperQode agent.yaml into a full HarnessSpec. The authoring shape intentionally supports the useful Omnigent-style fields SuperQode is adopting: executor, tools, skills, os_env, policies, and agent-valued tools.

superqode harness import-agent agent.yaml --output harness.yaml

Example:

name: coding_supervisor
prompt: Coordinate coding work through named tools and subagents.
executor:
  harness: codex
  model: databricks-gpt-5-5
skills:
  - code-review
tools:
  github:
    type: mcp
    command: uvx
    args: [github-mcp-server]
  reviewer:
    type: agent
    prompt: Review proposed changes for correctness and tests.
    executor:
      harness: claude-sdk
      model: claude-sonnet

MCP tool declarations are compiled into runtime.config.mcp_servers. Harness runtimes that support SuperQode's MCP bridge connect those servers for the run and expose discovered tools as mcp_<server>_<tool> tool calls.

Agent tool declarations are compiled into child AgentSpecs. This is the SuperQode runtime surface for Omnigent-style tools.<name>.type: agent entries. In the builtin harness runtime, the parent gets the agent_session tool for persistent child sessions:

agent_session(action="start", agent="reviewer", message="Review this diff", session_id="reviewer-main")
agent_session(action="resume", agent="reviewer", session_id="reviewer-main")
agent_session(action="send", agent="reviewer-main", message="Now check tests")
agent_session(action="wait", agent="reviewer-main")
agent_session(action="approve", agent="reviewer")
agent_session(action="reject", agent="reviewer", message="Use a safer command")
agent_session(action="close", agent="reviewer")

The session_id is optional on start; when supplied, another parent run can reattach to the child context later with resume.

Understanding And Verifying¶

harness explain¶

Explain in plain English what a harness lets the model do, and why. Reads the same resolved policy the runtime enforces, so the explanation is the truth, not a restatement of the YAML. Covers the model, tools, permissions, workflow, and context.

superqode harness explain --spec harness.yaml
superqode harness explain --spec harness.yaml --provider ollama --model qwen3-coder
superqode harness explain --spec harness.yaml --json

harness compile¶

Print the resolved spec and the effective runtime policy as JSON: model policy (temperature, tool-call format, iterations, parallelism) and the compiled permission config.

superqode harness compile --spec harness.yaml --provider ollama --model qwen3-coder

harness diff¶

Show policy, tool, and agent differences between two specs. Useful to confirm an edit changed exactly what you intended.

superqode harness diff base.yaml custom.yaml

harness validate¶

Validate a spec file, or emit the HarnessSpec JSON Schema. Unknown fields and incorrect field types are rejected instead of being silently ignored. Both plain and --json validation return a non-zero exit code for invalid specs, so the command can be used as a CI gate.

superqode harness validate harness.yaml
superqode harness validate --spec harness.yaml --json
superqode harness validate --schema

harness inspect¶

Inspect a spec together with backend capability compatibility (does the chosen runtime support the spec's workflow, tools, and sandbox).

superqode harness inspect --spec harness.yaml --runtime builtin --sandbox local

harness doctor¶

Diagnose a spec before running it: surfaces misconfigurations, backend mismatches, and store issues.

superqode harness doctor --spec harness.yaml

harness test¶

Run a quick readiness probe. Without --live, this validates spec loading, doctor checks, and kernel initialization. With --live, it also sends a small prompt to the configured model and returns a compact failure digest.

The failure digest classifies a failure by one of the nine harness dimensions (dimension: {id, label, field}, for example D1 model selection -> model_policy). The result identifies the failed operation and the corresponding specification field.

superqode harness test --spec harness.yaml
superqode harness test --spec harness.yaml --live --provider ollama --model qwen3-coder --json

harness eval¶

Run a task scorecard against one or more harness specs. Use --variant to compare task-specific specs against a baseline while keeping variants isolated.

It also acts as a seesaw gate: if any variant regresses a task the baseline solved, harness eval exits non-zero (code 2) so you can block a candidate before applying it. The per-variant regressions_vs_baseline and a top-level regressed / regressed_variants are in the JSON. Pass --allow-regressions to override the gate.

When a runtime exposes provider usage, eval JSON includes per-task and per-variant usage with tokens_in, tokens_out, total_tokens, cost_usd, plus tokens_per_success, cost_per_success, and latency_ms_per_success. Unknown provider usage remains null rather than estimated.

superqode harness eval --spec base.yaml --variant optimized.yaml --tasks tasks.yaml  # exits 2 on regression
superqode harness eval --spec base.yaml --variant optimized.yaml --tasks tasks.yaml --allow-regressions
superqode harness eval --spec base.yaml --tasks tasks.yaml --live --json
superqode harness eval --spec base.yaml --variant candidate.yaml --tasks tasks.yaml --split held-out

Exit codes: 0 ok, 1 an eval errored, 2 a variant regressed a baseline-solved task.

Task files are YAML:

tasks:
  - id: smoke
    split: held-in
    prompt: "Reply with hello"
    expect_contains: hello
  - id: heldout-smoke
    split: held-out
    prompt: "Reply with ready"
    expect_contains: ready

Use held-in for tasks the optimizer may see while proposing changes, and held-out for the final candidate gate. Tasks without split default to held-in.

harness eval-packs¶

List bundled eval packs, or print the path to one pack:

superqode harness eval-packs
superqode harness eval-packs local-recursive-smoke
superqode harness eval --spec harness.yaml --tasks "$(superqode harness eval-packs local-recursive-smoke)" --live

harness bench and harness bench-verify¶

Run a publishable same-model comparison from a HarnessBench manifest. The output preserves every raw repetition, aggregate quality/cost/latency variance, Pareto membership, source fingerprints, and artifact checksums.

superqode harness bench --manifest harnessbench.yaml --output results/july
superqode harness bench-verify results/july

The manifest fixes the task file, at least two HarnessSpecs, provider, model, runtime, sandbox, split, and repetition count. --live or --dry-run can override its execution setting. Dry runs validate packaging but are not valid promotion evidence. See HarnessBench.

harness auto-bench¶

Run the quick model-facing wrapper around harness test or harness eval and print a recommendation.

superqode harness auto-bench --spec harness.yaml
superqode harness auto-bench --spec harness.yaml --tasks tasks.yaml --live

harness mine-failures¶

Mine structured failure records from existing harness test --json or harness eval --json output. This does not change the harness; it creates evidence that can feed the logbook and harness improve.

superqode harness eval --spec harness.yaml --tasks tasks.yaml --live --json > eval.json
superqode harness mine-failures --eval-result eval.json --output .superqode/self-improve/failures.json
superqode harness mine-failures --harbor-run harbor-results/ --output .superqode/self-improve/failures.json

harness logbook¶

Maintain a repo-local, file-backed self-improvement logbook. The first MVP logbook stores recurring failure patterns under .superqode/self-improve/logbook/failure_patterns.yaml.

superqode harness logbook update --from-failures .superqode/self-improve/failures.json
superqode harness logbook show
superqode harness logbook export --output .superqode/self-improve/logbook.md
superqode harness logbook prune --min-count 2 --max-patterns 50

Logbook entries track count, confidence, status, first/last seen timestamps, source references, and negative-result slots. prune removes low-signal or stale memory while keeping active/pinned entries.

harness audit-candidate¶

Audit a proposed harness before accepting or applying it. The audit compares the base and candidate specs, checks editable/protected surfaces, detects permission widening and weakened checks, verifies held-out eval gates, and compares the proposal against the native candidate ledger.

superqode harness eval \
  --spec harness.yaml \
  --variant candidate.yaml \
  --tasks tasks.yaml \
  --split held-out \
  --live \
  --json > heldout.json

superqode harness audit-candidate \
  --base harness.yaml \
  --candidate candidate.yaml \
  --tasks tasks.yaml \
  --eval-result heldout.json \
  --require-heldout \
  --record

harness candidates¶

Inspect the native JSONL ledger of accepted and rejected self-improvement attempts. This is the durable negative-result memory used to avoid repeating failed edits.

superqode harness candidates list
superqode harness candidates show cand_1234abcd5678
superqode harness candidates export --output .superqode/self-improve/candidates.md

harness improve¶

Create a self-improvement meta-harness project from the current spec, eval tasks, mined failures, and logbook memory. It uses the same optional meta-harness backend as harness optimize, but appends self-improvement guidance to trace-evidence.md and records editable/protected harness surfaces.

If the task file has split: held-out tasks, harness improve includes held-out gating guidance and the exported meta-harness project includes dry split checks. When --apply is used, SuperQode audits the best candidate first and records the accepted/rejected decision in the candidate ledger.

You can version default improvement boundaries in the harness itself:

optimization:
  enabled: true
  require_human_apply: true
  editable_surfaces: [context, workflow, model_policy, agents.tools]
  protected_surfaces: [execution_policy, checks, approvals, sandbox]
  heldout_fraction: 0.3
  max_candidate_edits: 3

--surfaces and --protected-surfaces override the spec for one run.

superqode harness improve \
  --spec harness.yaml \
  --tasks tasks.yaml \
  --from-failures .superqode/self-improve/failures.json \
  --export-only

superqode harness improve \
  --spec harness.yaml \
  --tasks tasks.yaml \
  --from-failures .superqode/self-improve/failures.json \
  --backend codex \
  --budget 1

harness optimize¶

Export a HarnessSpec and eval task file into a superagentic-metaharness project, then optionally run a meta-harness backend. This keeps harness optimization optional and auditable: use --export-only to inspect the generated project, and use --apply only when you want the best candidate copied back.

superqode harness optimize --spec harness.yaml --tasks tasks.yaml --export-only
superqode harness optimize --spec harness.yaml --tasks tasks.yaml --test-result test.json --eval-result eval.json
superqode harness optimize --spec harness.yaml --tasks tasks.yaml --backend codex --budget 1
superqode harness optimize --spec harness.yaml --tasks tasks.yaml --backend codex --apply --output optimized.yaml
superqode harness optimize-inspect mh-project/runs/superqode-optimize
superqode harness optimize-ledger mh-project/runs/superqode-optimize

When --trace-evidence is omitted, SuperQode writes trace-evidence.md from the current spec and eval task file. The generated evidence includes the harness runtime, workflow, model policy, permission posture, and task prompts so the optimizer has a useful starting snapshot. Add --test-result or --eval-result to include previous scorecards and failure digests from prior runs.

Use harness optimize-inspect RUN_DIR to summarize a completed meta-harness run. Use harness optimize-ledger RUN_DIR to list candidates, objective values, validation state, outcomes, and changed files. Both commands support --json. The TUI harness sidebar also shows the latest local meta-harness run under .superqode/metaharness or mh-project when artifacts are present.

harness optimize-omni¶

Optimize a complete HarnessSpec through GEPA's engine-pluggable API. By default, Omni runs GEPA, AutoResearch, and GEPA meta-harness in parallel, then continues from the best candidate with a fresh GEPA engine.

superqode harness optimize-omni \
  --spec harness.yaml \
  --tasks eval-tasks.yaml \
  --engine omni \
  --max-evals 20 \
  --max-token-cost 4 \
  --live

The task file must contain at least one split: held-in task and one split: held-out task. Held-out tasks are sealed from optimization and used for a final seesaw gate. Every proposed YAML candidate is parsed and audited before rollout; permission widening, protected-surface changes, check weakening, and out-of-policy edits score zero.

The command never edits --spec. It writes the baseline, staged candidate, optimizer artifacts, candidate audit, held-out results, and reports under .superqode/harness-optimizations/. A failed audit or held-out regression exits with status 2 while retaining all artifacts for inspection.

This path needs a GEPA build containing OptimizeAnythingConfig and optimize_best_of. AutoResearch and GEPA meta-harness additionally require the Claude CLI. See Skill Optimization for installation details.

For a subscription-backed, low-usage smoke test and the minimum four-evaluation Omni command, see Tiny subscription experiment.

harness promote¶

Deliver an audited candidate through staging, deterministic WorkOrder canary routing, live held-out evidence, activation, and guarded rollback:

superqode harness promote stage \
  --base harness.yaml --candidate candidate.yaml \
  --tasks eval-tasks.yaml --eval-result heldout-eval.json \
  --actor maintainer

superqode harness promote canary cand_... --percent 10 --actor maintainer
superqode harness promote status cand_... --json
superqode harness promote select harness.yaml --key work_... --json
superqode harness promote activate cand_... \
  --evidence results/canary/scorecard.json --actor maintainer
superqode harness promote rollback cand_... \
  --actor maintainer --reason "cost regression"

Activation requires a passing live held-out HarnessBench scorecard whose base and candidate digests match the staged files. It rejects regression runs and candidates below the baseline mean. See Harness Promotion.

Running¶

harness run¶

Run a task through a spec or an installed Python harness. Single-prompt specs execute one turn through the kernel; non-single workflow specs execute their topology. Installed harnesses are addressed by name.

superqode harness run --spec harness.yaml \
  --provider ollama --model qwen3-coder \
  -p "Read README.md and summarize this project."

superqode harness run my-harness "Read README.md and summarize this project."

Run History And Debugging¶

These commands read the harness event store (default .superqode/sessions).

harness runs¶

List persisted runs, optionally filtered by session.

superqode harness runs
superqode harness runs --session <session-id>

harness events¶

Show normalized events for a run: model calls, tool calls, approvals, and results.

superqode harness events <run-id>
superqode harness events <run-id> --after 10

harness evidence¶

Show a readable evidence report for a run (what the agent did and the resulting workspace changes).

superqode harness evidence <run-id>

For recursive and dynamic workflow runs, the report includes child run lineage and any dynamic_workflow / dynamic_workflow_script plan tree recovered from tool result metadata.

harness observability status¶

Show local and optional external observability sink status.

superqode harness observability status
superqode harness observability status --spec harness.yaml --json

The command reports local JSONL export availability, OTEL-shaped export availability, and optional live sinks such as MLflow, LangSmith, Logfire, and Arize/Phoenix. Install the optional SDK set for these integrations:

uv sync --extra observability

Missing optional packages or credentials are reported, not treated as run failures.

harness observability export¶

Export a persisted run tree to local observability artifacts and any configured optional sink.

superqode harness observability export <run-id>
superqode harness observability export <run-id> --spec harness.yaml --output .superqode/obs/<run-id>

The export includes:

• trace.json: complete normalized run tree
• runs.jsonl: one row per root/child run
• events.jsonl: normalized harness events
• otel_spans.jsonl: OTEL-shaped spans for trace backends
• overview.md: human-readable summary

MLflow, when enabled and installed, logs the export directory as artifacts. LangSmith creates a run tree, Logfire mirrors the run as spans and log events, and Arize/Phoenix uses the OTEL collector endpoint path.

harness graph¶

Show the planned graph for a spec, or the persisted event graph for a run.

superqode harness graph --spec harness.yaml
superqode harness graph <run-id>

harness replay¶

Show a replay plan for a persisted run, or re-execute it with --execute.

superqode harness replay <run-id>
superqode harness replay <run-id> --execute --provider ollama --model qwen3-coder

For dynamic runs, replay output shows the compiled script/plan, step ids, fan-out markers, and child run ids alongside the normal lineage tree.

harness fork¶

Fork a persisted run by copying its event prefix up to a chosen index, so you can branch a new run from an earlier point.

superqode harness fork <run-id> --after 8 --session new-branch

Durable Inputs (Long-Running Sessions)¶

For always-on or queued workloads, a harness session has a durable inbox. Inputs are admitted, then drained by a one-shot drain or a long-running worker.

harness inbox¶

Manage durable session inputs.

superqode harness inbox add --session <id> --prompt "Refactor the auth module"
superqode harness inbox list --session <id> --status pending
superqode harness inbox recover --session <id> --stale-after 300

harness drain¶

Execute pending durable inputs for one session, then exit. Drains --limit inputs (default 1).

superqode harness drain --spec harness.yaml --session <id> \
  --provider ollama --model qwen3-coder

harness worker¶

Run a durable inbox worker loop that claims and drains inputs until stopped (or until --once / --max-runs).

superqode harness worker --spec harness.yaml --session <id> \
  --provider ollama --model qwen3-coder --concurrency 2

Harness Protocol¶

harness protocol¶

Inspect Harness Protocol v1 and validate its deterministic reference adapter.

superqode harness protocol list
superqode harness protocol describe
superqode harness protocol describe acp --json
superqode harness protocol conformance
superqode harness protocol conformance my-harness

Installed package harnesses can use the normal run command:

superqode harness run my-harness "review this diff"

With no harness ID, conformance uses a deterministic offline reference. With an ID, it executes that installed harness. Live model or ACP adapters may require provider credentials or a running agent. See Harness Protocol v1.

Sharing¶

harness registry¶

Use the local registry as a low-risk share hub before moving to a remote marketplace. Publishing validates and copies a spec into ~/.superqode/harness-registry; installing copies it back into a project.

superqode harness registry publish harness.yaml
superqode harness registry list
superqode harness registry install team-coder --output harness.yaml

Related¶

• Bring Your Own Harness: guided walkthrough.
• Harness System: full spec-field reference.
• Configuration vs Harness: how harness.yaml differs from superqode.yaml.
• Runtime Backends: the engines a harness can run on.