Bring Your Own Harness¶

A harness is a single YAML file that decides how your coding agent behaves: which model it uses, which tools it can call, whether it can write files or run shell commands, and how it asks for approval. You own this file. It lives in your repo, you can read it, edit it, and check it into git. Nothing about your agent is hidden "SuperQode magic". When a run does something you did not expect, the harness tells you why.

This guide shows you how to create one, understand it in plain English, customize it, and run it against a local model.

Why This Matters For Local Models¶

With a frontier API you mostly trust the provider's defaults. With a local model you are the operator. You choose the model, the context size, and how much the agent is allowed to do on your machine. A harness makes those choices explicit and repeatable:

• You pay once in hardware, not forever in token bills.
• The same harness file gives you the same behavior every time.
• If a small local model is unreliable with native tool calls, you can switch it to prompt tool-call format in one line.
• A read-only "reviewer" harness can never edit your files, no matter what the model decides.

Step 1: Get A Harness¶

You almost never need to write a harness from scratch. You have three ways to get one, from easiest to most manual.

Option A: The wizard (recommended)¶

The wizard asks a few plain questions and writes the file for you. No YAML editing required to get started:

superqode harness wizard

It asks for a name, a starting point (model family), the provider/model, whether the agent may write files or run shell commands, the approval style, the tool-call format, and an optional multi-agent workflow. Then it writes harness.yaml and immediately explains what it built in plain English.

Option B: Start from an optimized template¶

SuperQode ships templates tuned per model family. Pick the one closest to your model and edit from there:

superqode harness init my-coder -t qwen-coding

List them anytime with superqode harness list-templates.

Option C: Let the doctor tune it for your hardware¶

superqode local init --repo .

That detects your machine, picks a trusted model, and generates superqode.local.yaml using the same harness format.

All three produce the same kind of file. Whichever you use, the next steps are identical.

Step 2: Understand It In Plain English¶

This is the command that makes the harness transparent. It reads the resolved policy (the exact same policy the runtime uses) and explains it in words:

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

Example output:

Harness: my-coder

'my-coder' is a coding harness: it gives the model read_file, write_file,
edit_file, grep, bash, and more to work in your repository, under the
permission rules below.

Model
  - Primary model: ollama/qwen3-coder.
  - Temperature 0.1 (lower is more deterministic, better for code).
  - Parallel tool calls are OFF (one tool at a time, safer for local models).

Permissions
  - Reading files and searching the repo: allowed.
  - Writing/editing files: allowed.
  - Running shell commands: allowed.
  - Network access: blocked (offline by default).
  - Approval profile 'balanced': auto-approves safe reads/searches but asks
    before writes and shell commands.

Workflow
  - Single agent handles the whole task.

If you ever wonder "what can this agent actually do to my repo?", run explain and read the answer.

Step 3: Edit It¶

The harness file is plain YAML. Here are the fields you will touch most often.

Choose the model¶

model_policy:
  primary: ollama/qwen3-coder
  temperature: 0.1
  context_window: 16384

Control what the agent can do¶

execution_policy:
  allow_read: true      # read and search files
  allow_write: true     # create and edit files
  allow_shell: true     # run shell commands
  allow_network: false  # reach the internet
  approval_profile: balanced  # ask before writes and shell

Set allow_write: false and allow_shell: false to get a safe read-only reviewer that can look at your code but can never change it or run commands.

Help weak local models call tools reliably¶

Small local models often produce malformed native tool calls. Switch them to prompt format, where tools are described in the prompt and parsed from text:

model_policy:
  primary: ollama/gemma4
  tool_call_format: prompt

After this, explain will report: "Tool calls use PROMPT format... because this model has weak or unreliable native tool support."

Block specific commands¶

execution_policy:
  permission_rules:
    - tool: bash
      pattern: "rm *"
      action: deny

Step 4: Verify Your Changes¶

Two commands confirm an edit did what you meant.

See the fully resolved policy as structured data:

superqode harness compile --spec harness.yaml

Compare two harnesses to see exactly what changed:

superqode harness diff harness.yaml locked.yaml

Catch mistakes before you run:

superqode harness validate harness.yaml

Step 5: Run It¶

Interactive TUI:

superqode --harness harness.yaml

One-shot headless task:

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

The agent now behaves exactly as explain described. If your harness blocks shell commands, the model cannot run them even if it tries.

What Happens Under The Hood¶

Nothing here is cosmetic. When you load a harness, SuperQode turns your YAML into real runtime rules:

1. execution_policy.allow_write / allow_shell / allow_network become hard permission rules. A blocked tool group is denied at the permission layer, before the tool ever runs.
2. model_policy sets the actual temperature, tool-call format, iteration limit, history limit, and whether parallel tool calls are allowed.
3. agents[].tools filters the tool registry, so the model only ever sees the tools you listed.
4. workflow decides whether one agent handles the task or it flows through planner, implementer, and reviewer roles.
5. context controls which instruction files load, where sessions are stored, and when the conversation compacts.

You can prove this to yourself: set allow_shell: false, run harness explain, and you will see "Running shell commands: BLOCKED". Run a task that asks the model to use the shell, and the permission layer refuses it.

A Read-Only Reviewer Example¶

version: 1
name: local-reviewer
flavor: coding
runtime:
  backend: builtin
model_policy:
  primary: ollama/qwen3-coder
  temperature: 0.1
  tool_call_format: prompt
execution_policy:
  sandbox: local
  approval_profile: balanced
  allow_read: true
  allow_write: false
  allow_shell: false
  allow_network: false
agents:
  - id: reviewer
    role: review
    tools:
      - read_file
      - grep
      - glob
      - repo_search

Run superqode harness explain --spec local-reviewer.yaml and the Permissions section will confirm writes and shell are blocked. This harness can read and analyze your repository but can never modify it.

Next Steps¶

• Harness System: the full field-by-field reference.
• Configuration vs Harness: how harness.yaml differs from superqode.yaml.
• Local Models: get a local server and model running first.
• Local Agentic Coding: the local-first positioning and workflow.