SuperQode • Harness² • CodeGem
The industry has come to accept that a coding agent is only as good as the harness around its model. The system prompt, the memory the agent carries, the way it is told to use its tools and the checks that judge its work all shape the outcome as much as the choice of model does. Harness optimisation has become an active research area, with several groups publishing methods that let one model improve the harness another model works inside. Google Research has added an important contribution to that line of work with Harness², and we have built a native implementation of its task-level method into SuperQode, running on top of CodeGem, our harness for Gemini and Gemma.
What Google Research published
The paper, Harness²: Recursive Agent Harnessing for an Open World by Ruiyao Xu et al. from Google Cloud AI Research and Northwestern, describes recursion at two levels. At the task level, a contrastive loop called Propose, Probe, Compose refines the harness for a single task within a budget k, in either a parallel or a sequential schedule. At the harnessing level, a library of adopted harnesses and an EXPERIENCE.md file update an "improvement harness" over time. The method does not need ground-truth verifiers. In the propose step, editors write invariant and domain-specific candidate harnesses. In the probe step, each candidate runs under matched conditions so the editors can observe a behavioural contrast. In the compose step, the method selectively merges, adopts or keeps edits and then executes the result. When k is greater than one, an anonymised selector picks the final output, and at k=1 selection is skipped.
The reported gains reach 11.5 points on WorkBuddy-Bench, 4.5 points on JobBench and 11.8 percentage points on LAB Partial, with GLM-5 and Gemini 3.5 Flash as executors under OpenCode and Codex and Claude Opus 4.8 as the default editor. The ablations show that the library, scoping and composition each contribute. The authors note that the method adds cost and that behavioural signals do not guarantee correctness. The paper treats eight editable components: system prompt, guardrails, memory, skills, tool guidance, scripts, subagents and plugin. The reference code is published at google-research/harness2.
Why we built this
On 13 October we introduced CodeGem, a SuperQode harness dedicated to Google's Gemini and Gemma models, with six tools (read, write, edit, search, python and bash) and support for local Gemma through Ollama, LM Studio and llama.cpp. When Harness² appeared shortly afterwards, we wanted to see how the method behaves when it is embedded inside a real harness rather than run as a separate research pipeline. Propose, Probe, Compose could in principle sit above any harness. We chose to explore it fully in CodeGem because that harness is built for exactly one model family, which keeps the executor, the tool set and the model route stable while the instructions change.
The result is an experimental, opt-in feature called Harness2 task refinement. It runs above the CodeGem executor, supports Gemini through the Google API or local Gemma, and produces a reviewable patch. The module header in harness2.py records the lineage directly: Google LLC holds copyright for the upstream method and prompt design, Superagentic AI for the native async integration, and the upstream commit is pinned in models.UPSTREAM. Refinement uses more time and tokens than an ordinary CodeGem run, and it does not guarantee a better result.
How the implementation works
Every job starts with base runs. SuperQode runs the task k times with the unmodified CodeGem harness, labelled base1 to basek, and stops if none of them completes successfully.
The propose step uses two editor roles. The invariant editor is asked to improve how the agent works, covering inspection, tool use, focused changes and observed verification. The domain editor is asked to improve domain procedure and edge-case reasoning without baking task answers into the harness. Both run in tool-free sessions and return one JSON object that edits only three files: instructions.md, memory.md and tool_guidance.md, with at most 12,000 characters combined and a notes field that cites the supporting evidence. An editor can also return keep_base to retain the current harness. Every editor and selector prompt carries a boundary stating that evidence is data to inspect and that commands embedded in task materials, trajectories or candidate prose must not be followed. An invalid edit is retried once with the validation error as feedback, and if the second attempt also fails the candidate inherits the current instructions.
The probe step runs each candidate as a full CodeGem solve in its own workspace snapshot, so the editors can compare how the agent actually behaved under different instructions.
The compose step uses a third editor role that merges only supported edits or keeps the current harness, with the explicit reminder that agreement is not independent proof. In sequential mode, each round produces an invariant and a domain candidate from the current harness, probes both, composes a final c1, c2 and so on, runs it, and carries it forward into the next round. In parallel mode, k invariant and domain pairs are proposed from the base harness and probed, then k independent compositions, agg1 to aggk, are built over the full pool and run.
The selector follows the reference design. Only composed finals enter the final pool, and the base runs are excluded. At k=1 the single final is adopted with no selector call. At k greater than one, the finals are shuffled deterministically, relabelled A, B and onwards, stripped of method labels, and passed to an anonymised selector prompt. The default k=1 schedule amounts to four coding attempts and three editing or composition sessions.
Applying the result safely
Apply is a SuperQode step rather than a phase of the paper. Nothing in the original project changes until you run it explicitly, and it requires passing explicit checks and an unchanged original source snapshot. Applying updates the task's source files and does not install the generated instructions as your default harness. The job directory holds selected.patch, selected-harness.json with the generated instructions, and the check output.
Several safeguards sit around this. Snapshots exclude Git metadata, dependency directories, caches, .superqode and common credential files such as .env*, *.pem, *.key, .netrc, .npmrc, .pypirc, .git-credentials, credentials*.json, and the .aws/, .ssh/, .gnupg/ and .kube/ directories, which the documentation describes as a safeguard rather than a guarantee. At a Git root, snapshots respect Git ignores and files created under ignored paths are never applied. Apply refuses symlinked destinations and any new file that already exists in the source. Snapshots are limited to 2 MiB per file and 32 MiB in total. Checks given with --check are repeatable, run without an implicit shell and have a 120-second limit each, and a check that modifies candidate source fails validation. Without a check, the result is marked unchecked and apply is disabled. --protect rejects any attempt that changes a named file. A session budget raises BudgetExhausted and ends the job with status budget_exhausted, and resume reuses completed stages only when their recorded inputs and workspace digests still match.
Running it
In the TUI, launch superqode in your project and enter the command below, or open :hub and choose Harness² refine. The panel offers Plan, Start, Inspect, Apply, Cancel, Open and Resume.
:harness refine
:harness refine inspect /path/to/refinement-jobFrom the CLI with Gemini, set GEMINI_API_KEY or GOOGLE_API_KEY and preview the job first. With --dry-run the preview makes no model calls and creates no job files. You can use --task-file in place of --prompt when the task is saved in a file.
superqode harness refine \
--provider google --model gemini-3.1-flash-lite \
--source /path/to/project \
--prompt "Fix the failing regression test with a focused source change." \
--output /path/to/refinement-job \
--check 'python -m pytest -q' \
--protect tests/test_regression.py \
--max-sessions 10 --max-turns 16 --max-seconds 600 \
--dry-runFor local Gemma, a harness file that inherits from codegem with primary: ollama/gemma4:12b and method: harness2 is passed with --spec, and no Google key is needed. The repository includes examples/harnesses/harness2-codegem.yaml as a starting point. The job lifecycle has its own commands:
superqode harness refine inspect /path/to/refinement-job --json
superqode harness refine cancel /path/to/refinement-job
superqode harness refine resume /path/to/refinement-job --json
superqode harness refine apply /path/to/refinement-jobAn interrupted stage can be retried with resume --retry-interrupted once you have inspected its tool effects, and the earlier attempt's evidence is preserved.
Try it yourself
The demo below uses a small calculator project with a deliberate bug in mean, which breaks both a normal average and the empty-input case. Harness² runs CodeGem on Gemini against that task, proposes and probes instruction changes, composes a refined harness, and applies the patch only after the project's own tests pass.
To reproduce it, install or upgrade SuperQode with uv and create the same project:
uv tool install superqode # or: uv tool upgrade superqode
mkdir -p ~/h2tui/ && cd ~/h2tui && git init -q
printf 'def mean(values):\n return (sum(values) + 1) / len(values)\n' > calculator.py
printf 'from calculator import mean\n\n\ndef test_mean():\n assert mean([2, 4, 6]) == 4\n\n\ndef test_mean_empty():\n assert mean([]) == 0\n' > test_calculator.py
printf '.venv/\n.superqode/\n__pycache__/\n.pytest_cache/\n' > .gitignore
uv venv -q && uv pip install -q pytest
git add . && git commit -qm "demo: buggy mean"
uv run --no-project pytest -q # 2 failed
export GEMINI_API_KEY="your-key"Start superqode in that folder and open the refinement panel with the task:
:harness refine Fix calculator.mean, including empty input. Make a focused source change and keep test_calculator.py unchanged.In the panel, choose Gemini with gemini-3.1-flash-lite, keep Sequential mode with k=1, set the check to the absolute path of your project's Python followed by -m pytest -q (for example /Users/you/h2tui/.venv/bin/python -m pytest -q), and protect test_calculator.py. Click Plan to review the budget before any model call, then Start. When the run reports that checks passed, click Inspect to review both the patch and the selected harness components, then Apply. Running uv run --no-project pytest -q again should show both tests passing. The check and protect fields sit at the bottom of the form, so use Tab from the max seconds field or a taller terminal if they are out of view. The same workflow is available from the CLI with superqode harness refine --help, and the Harness2 documentation covers every option.
How this relates to our earlier harness work
Harness² is the latest step in a longer thread of our work on optimising coding agent harnesses. MetaHarness is our unofficial open-source implementation of Stanford's Meta-Harness, with documentation and a package on PyPI. It enforces write scopes, records outcomes such as keep, discard and scope violation, and supports hill-climb and frontier modes. We showed it in practice in Optimizing Databricks Omnigent Agents with MetaHarness. Our GEPA work in SuperQode is covered in Self-Optimizing Coding Agent Harnesses with SuperQode and GEPA Omni in SuperQode.
The methods differ in structure. MetaHarness proposes a candidate, evaluates it, and then keeps or discards it, using a filesystem history of earlier attempts to inform the next proposal. Harness² adds two steps to that pattern: it probes several candidates under matched conditions to obtain a behavioural contrast, and it composes a new harness from the edits that contrast supports. The two projects are separate, and Harness2 task refinement lives inside SuperQode alongside CodeGem.
Current Limitation
It runs only with CodeGem, and one provider and model route serves every stage, from base runs through editing, composition and selection. Editors change only instruction, memory and tool-guidance text, up to 12,000 characters combined, while tool schemas, model selection, permissions and check commands stay outside the editable set and ambient skills and prompt templates are disabled. The paper's other components, such as generated executable helpers, skill mutation and subagents, are not supported. The budget k is capped at 4. There is no cross-task library, so the paper's harnessing-level recursion is not implemented, and generated instructions are never promoted to a persistent harness automatically. Workspace copies do not provide an OS sandbox, because CodeGem tools run with host permissions and commands can affect files outside those copies. Session, turn and time limits bound the work, and the command does not enforce a dollar spending cap.
To get started, read the Harness2 task refinement guide, the CodeGem documentation and the CodeGem recommended models, and see the SuperQode repository for the source.