MetaHarnessAdapter is a framework for training and evolving AI agent harnesses from task feedback. A harness adapter is a deployable package of instructions, skills, roles, and tools that extends an existing agent without changing its model weights. You provide tasks, an acting agent, and an evaluator; the framework runs the agent, collects feedback, and applies a configurable learning method to improve the adapter, checking and versioning each update.
- [2026/10]
harnessadapter convertemits an adapter as an installable plugin for Claude Code, Codex, Pi and Hermes (#6). - [2026/10] MetaWorld Model (MWM) is a built-in template and Evolver, with CL-Bench and ServeLearnBench examples (#7, #8).
- [2026/10] GEPA and SkillOpt run as built-in Evolvers, with OfficeQA in the SkillOpt paper's setting (#2).
- [2026/10] v0.2.0: the evolution framework, with adapter templates, Evolvers, the Trainer and evolving tasks.
| You want to... | MetaHarnessAdapter gives you |
|---|---|
| Make Codex, Claude Code or your own agent better at your tasks without touching its weights | An adapter (context, skills, roles, MCP tools) learned from the agent's own attempts and your judge |
| Compare learning methods on the same task | One task interface; swap evolver.name between prompt_only, codex, claude, gepa, skillopt, mwm |
| Know exactly what changed and why | Every accepted step is a Git commit; runs are branches, checkpoints and finals are tags; each final adapter carries a CARD.md with its scores |
| Ship what was learned | deploy writes it into a project workspace; convert packages it as a native plugin for four hosts |
The four parts map onto the parts of ordinary model training:
| Part | Role | Like |
|---|---|---|
| Adapter template | The structure and its specification: which files are learnable, which are fixed, and a checker | the initial model |
| Evolver | The learning algorithm: a learner's harness (one model call, a Codex or Claude agent, GEPA, SkillOpt, MWM) | the optimizer |
| Trainer | The outer loop: data, rollouts, learning material, checks, Git, budgets and records | the trainer |
| Evolving task | Your task description, data, judge and acting-agent pipeline | data + reward + rollout |
An adapter is one directory with two ends. The consumption end is what an acting agent receives, in the shape of a
plugin: ADAPTER.md, skills/, agents/ and tools behind an MCP entry, optionally backed by a standalone service.
The training end is what a learner works within: adapter.yaml (learnable and fixed files, the check),
EVOLVER.md, and the Git tree of every version. See What is a harness adapter?
git clone https://github.com/haizhongzheng/MetaHarnessAdapter.git
cd MetaHarnessAdapter
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e . # add '.[gepa]' or '.[skillopt]' for those Evolvers
harnessadapter --helpPython 3.11+ and Git are required. Sandboxed agent Evolvers need Linux with bubblewrap; inspecting and deploying
adapters works on macOS too. Per-integration requirements are in Installation.
Deploy an adapter (no model calls, no dataset):
mkdir -p .demo && cp -R harnessadapter/algorithms/templates/prompt_only .demo/adapter
harnessadapter deploy --adapter .demo/adapter --workspace .demo/codex-workspace --host codex
cat .demo/codex-workspace/AGENTS.md # the adapter's context, as Codex will read itTrain one from task feedback:
python examples/officeqa/utils/prepare.py /path/to/officeqa/prepared
harnessadapter check --config examples/officeqa/gepa/smoke.yaml # catch setting mistakes before spending
harnessadapter train --config examples/officeqa/gepa/smoke.yaml # resumes after a crash
harnessadapter eval --config examples/officeqa/gepa/smoke.yaml --adapter finalRun it on your own server instead of a hosted model (models are <backend>/<model id> references; a backend
is an endpoint, see Model backends):
vllm serve Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 --enable-auto-tool-choice --tool-call-parser hermes # http://127.0.0.1:8000/v1
harnessadapter backends check vllm/Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 # chat, Responses and Messages APIs answer?
harnessadapter train --config examples/officeqa/gepa/smoke.yaml model=vllm/Qwen/Qwen3-30B-A3B-Instruct-2507-FP8Ship it into a project, or as a plugin:
harnessadapter deploy --adapter DIR --workspace WORKSPACE --host claude-code
harnessadapter convert --adapter DIR --output OUT --target codex # or claude-code, pi, hermesThe full walkthrough is in the Quick Start.
Evolvers (learning methods)
evolver.name |
Method |
|---|---|
prompt_only |
One model call per step rewrites ADAPTER.md from the step's results |
codex / claude |
A Codex or Claude Code agent edits the adapter from the step's learning material |
gepa |
GEPA: reflective text evolution with Pareto selection |
skillopt |
SkillOpt: a few validation-gated skill edits per step, under a learning rate |
mwm |
MetaWorld Model: a learner maintains a world model of the environment after every block of episodes |
To write your own, subclass Evolver and implement step; see Custom Evolver.
Adapter templates: prompt_only (context only), lean_collab (skills, a shared lemma library and a team service
for agents proving Lean theorems together), mwm (memory, briefing and callable programs behind one wm tool).
Hosts
| Host | deploy into a workspace |
convert to a plugin |
|---|---|---|
| Codex | ✓ | ✓ |
| Claude Code | ✓ | ✓ |
| Pi | ✓ | |
| Hermes | ✓ | |
| Your own agent loop | reads the adapter's context and tools directly |
| Recipe | Task | Evolvers | Result |
|---|---|---|---|
| OfficeQA | 133 questions on U.S. Treasury Bulletins; a GLM 5.3 Flash agent searches the bulletins | prompt_only, codex, gepa, skillopt |
in each adapter's CARD.md |
| OfficeQA, SkillOpt paper setting | The paper's 50 / 24 / 172 split, exact-match scorer | skillopt, gepa |
test mean score 0.576 (skillopt), 0.564 (gepa); 172 questions × 3 repeats |
| Lean collaboration | Five Codex agents proving Lean theorems with one shared team service | (finished adapter) | 8/8 on the development set; 12/24 held-out problems so far |
| ServeLearnBench | retail_l3: 624 serving cases in 8 windows | mwm, prompt_only |
per-window tests with slb score |
| CL-Bench | database and poker streams | mwm, prompt_only |
accuracy per stream |
Every trained adapter in examples/ comes with its CARD.md: how it was trained, how it
scored, and where it has not been tested.
- What is a harness adapter?: the package from both ends
- Installation and Quick Start
- Using and training adapters: files, deployment and handoffs
- Tutorials: deploy an adapter, reproduce a result, bring your own task, customize an adapter, write your own Evolver
- Overview and the components: Adapter, Evolver, Trainer, Task
- Reference: Configuration, Commands, Adapter manifest
Build the docs site locally with docs/build.sh, and serve it with docs/serve.sh.