Configuration vs Harness¶

SuperQode has two YAML files with very different jobs, and the distinction matters: one describes your environment, the other describes a run.

superqode.local.yaml is a HarnessSpec too. It is generated by the local setup flow and is named differently so it is obvious that the file targets the current machine and local model stack.

They compose: a harness run executes inside the environment your configuration provides. The harness says "use the ds4 tool profile with a workspace sandbox and ask before shell commands"; your configuration supplies the provider credentials, MCP servers, and permission defaults that environment offers.

The harness lifecycle, end to end¶

Everything below is a real, runnable path. Try it in any repository.

1. Create¶

Answer a few questions and let the wizard write it (recommended, no YAML editing), start from a built-in template, or write the YAML from scratch:

superqode harness wizard                                              # interactive builder
superqode harness list-templates
superqode harness init my-coder --template qwen-coding --output harness.yaml
superqode harness init local --template gemma4-coding --output harness.yaml

Templates include coding, no-tool, qwen-coding, glm-coding, glm52-coding, gemma4-coding, gemma4-no-tool, ds4-coding, and ds4-fast-local. The model-family templates ship model policies already tuned for those families. glm52-coding targets Z.AI's first-party general API and never selects the restricted Coding Plan endpoint.

See exactly what any harness will do, in plain English:

superqode harness explain --spec harness.yaml

For the full step-by-step walkthrough, see Bring Your Own Harness.

2. Define¶

The spec is a complete contract. Every section is optional with sensible defaults:

version: 1
name: my-coder
flavor: coding                  # or no_tool

runtime:
  backend: builtin              # adk | openai-agents | codex-sdk | claude-agent-sdk | deepagents | pydanticai
  fallback_backends: []

model_policy:
  primary: ollama/gemma4
  fallbacks: ["lmstudio/qwen3-coder"]
  temperature: 0.2
  context_window: 16384         # pin it, or let live detection decide
  tool_call_format: prompt      # for models without a native tool-calling head

execution_policy:
  sandbox: local                # OS sandbox for shell commands
  approval_profile: balanced
  allow_write: true
  allow_shell: true
  permission_rules:             # first match wins
    - { tool: bash, pattern: "pytest*", action: allow }
    - { tool: bash, pattern: "git push*", action: ask }

workflow:
  mode: single                  # chain | parallel | router | orchestrator | evaluator_optimizer

context:
  instruction_files: ["AGENTS.md"]
  session_storage: .superqode/sessions

checks:                         # commands that verify the work
  steps:
    - { name: tests, run: "pytest -q" }

You can go further: an agents: section defines named roles with their own model, system prompt, tool list, and delegation graph for multi-agent workflows.

3. Validate¶

superqode harness validate harness.yaml
superqode harness inspect --spec harness.yaml     # resolved policy, workflow, tools
superqode harness compile --spec harness.yaml     # the exact effective contract
superqode harness doctor --spec harness.yaml      # backend installed? sandbox available? store ready?
superqode harness diff a.yaml b.yaml              # what changed between two specs

doctor is the share gate: run it before giving a spec to a teammate so missing backends or sandbox tools surface on your machine, not theirs.

4. Run¶

A harness executes anywhere SuperQode runs:

The single-prompt paths (harness run --single-step, TUI chat) execute through the harness kernel. Non-single CLI runs, :workflow run, the MCP server, and the Python run_workflow() API execute the spec's chain, parallel, router, orchestrator, or evaluator-optimizer topology.

5. Observe¶

Every run leaves a normalized event trail, no matter which runtime executed it:

superqode harness runs                  # recent runs
superqode harness events <run-id>      # model calls, tool calls, approvals, results
superqode harness graph <run-id>       # the event graph (add --json for machines)
superqode harness evidence <run-id>    # checks output and verification evidence

6. Reuse and share¶

Commit harness.yaml next to your code. A teammate with SuperQode installed runs the same contract with one command, and harness doctor tells them if their machine is missing anything. Expose it over MCP and it becomes a tool inside Claude Desktop or any other MCP client. Serve it over A2A and it becomes an agent other agents can call.

Which file do I edit?¶

See Harness System for the full spec reference and superqode.yaml Reference for the configuration schema.