MetaHarness
Mint a custom AI agent harness from any repo.
npx metaharness · open the Studio →
(Repo: ruvnet/metaharness · CLI: metaharness · Library: @ruvnet/agent-harness-generator)
Explore the full animated walkthrough → · 12 chapters · 96-second full tour · 32-second preview
Earlier 20-chapter capability tour · Open the Studio
What this is
Every serious repo deserves its own agent. A repo-aware CLI, a repo-aware coding agent, a local MCP server, memory scoped to the project, skills generated from the actual file layout, governance policy, release verification, witness-signed provenance.
metaharness mints those, on demand, from a GitHub URL or a blank slate. It is not another agent framework. It is a factory for agent frameworks.
The model is replaceable. The harness is the product.
What it gives you
In under 60 seconds, in your browser, with nothing leaving your machine:
- A custom AI agent harness for your repo (or any repo)
- Recommended agents, skills, slash commands, MCP tools
- A scoped memory namespace + governance policy
- Witness-signed provenance + release gates
- Drops into Claude Code, OpenAI Codex, pi.dev, Hermes, OpenClaw, RVM, or Prime Agent — pick one or all
Output is an npm-publishable .zip with your name on it, your branding, your npx <your-name> CLI.
New
Watch Darwin evolve a harness · Explore model routing · Review experimental extensions
- Run an experimental ARC-AGI-3 harness from the ChatGPT UI.
@metaharness/arc-agi-3owns exact observations, persistent evidence-backed memory, belief-state exploration, guarded actions, supervisor interventions, checkpoints, and hash-chained receipts.@metaharness/arc-agi-3-chatgptexposes that controller as a remote MCP server and MCP Apps canvas for ChatGPT Developer Mode. ChatGPT is the OpenAI reasoning host: neither package uses the OpenAI API or anOPENAI_API_KEY. An opt-in ARC-specific AVO loop adds governed candidate selection, lineage, memory, blocking supervision, and an explicitly separate retrodiction arm. The frozen synthetic mechanism gate passes, and one actor-declared-clean single-game smoke favored AVO 3.2676 to 0.3968, but that non-competition result is not claim-eligible. All packages remain private and experimental; no ARC performance claim is made until an official closed scorecard satisfies the frozen controlled-ablation gate in ADR-254. - Governed autonomous variation for difficult engineering work.
@metaharness/avolets an agent repeatedly inspect, edit, execute real tools, evaluate, repair/revert, branch, consult structured RVF memory, and commit—while MetaHarness retains immutable capabilities, budgets, promotion, quarantine, rollback, and signed replay receipts. Simple work stays on Darwin's fast path. The runtime has a deterministic 205-action RVF interruption proof; the stronger “AVO-class” claim remains blocked on the preregistered 100-task unseen SWE-bench gate in ADR-251. ADR-276 now enforces that boundary at publication against the exact tag SHA and npm tarball, protected claim semantics, measured cost, lineage roots, and two independent graders. - Run your harness on Prime Agent — and borrow its best ideas. The 10th host
(
@metaharness/host-prime-agent,--host prime-agent) emits your tools as project-scoped, Python-backed Prime Agent skills (.prime/agent/skills/— the host has no MCP) plus an install runbook. Fail-closed: Prime Agent can't enforce a deny-list itself, so a non-empty deny-list ships a prominent instead of silently dropping your posture. From its design we also shipped — an evidence-backed proposer in that must cite the failing traces behind each edit or propose nothing — and an opt-in crash-recoverable JSONL session log whose Rust and TS (wasm) replays produce identical state hashes. Its PTC ("kernel as the only tool") claim is honestly behind a pre-registered A/B in . See / . ($0)
Tune it to your project — then ship it as your own npm
A generated harness is a starting point you own, not a fixed framework. Open it and make it yours:
- Keep only what your repo needs. Delete the agents, skills, slash commands,
and MCP servers you won't use — the scaffold ships a recommended set, but a
payments service and a docs site want very different harnesses. A smaller,
targeted harness is faster, cheaper, and easier to reason about.
harness doctor/harness validatekeep it healthy as you trim. - Optimize the model routing for your work. Swap the per-task model tiers, tighten the governance policy, point the memory namespace at your domain. The harness is config you control, not a black box.
- Publish it as your own package for the whole org. Rename it, set your
scope, and
npm publish— now anyone on your team runsnpx @your-org/your-harnessand gets the same repo-tuned agent. One command, org-wide, versioned like any other dependency. (The 19@metaharness/*examples are exactly this pattern, published live.)
Make older, cheaper models punch like frontier ones. The right harness isn't a pile of extra steps bolted onto an expensive model — it's putting the right model on each task and getting out of the way. Our DRACO benchmark proves it: a small, cheap model delivers frontier-quality research at roughly one-tenth the cost, and a smart router squeezes out the rest. Stop paying frontier prices for work a $0.10 model does just as well.
That router ships as @metaharness/router
— route(query) returns the cheapest model predicted to clear your quality bar,
learned from your own eval logs. npm i @metaharness/router.
Try it in 30 seconds
# In the browser — zero install, nothing leaves the page
open https://ruvnet.github.io/metaharness/
# Or in the terminal — the same harness (behaviourally equivalent output)
npx metaharness my-bot --template vertical:coding --host claude-code
cd my-bot && npx . --help
Don't know what to pick? Run the wizard:
npx metaharness --wizard
Already have a repo you want a harness for?
harness analyze-repo . # local — deterministic analysis only
harness analyze-repo . --scaffold my-bot # materialise the recommended harness
No repository code is executed. Inferred build/test commands are emitted as trust: inferred · execution: disabled.
📖 Read the plain-language user guide →
Hosts
The same harness output runs on ten agent hosts — nine interactive, plus GitHub Actions (CI/CD):
See ADR-004 — Host integration model and ADR-033 — GitHub Actions host.
MCP — modular, default-deny
MCP is included as a first-class adapter surface, not the identity. It is gated and default-deny (ADR-022):
- Modes:
off·local(stdio) ·remote(HTTPS + auth) - Emits
src/mcp/{server,tools,resources,prompts,policy,audit}.ts+ a scannable.harness/mcp-policy.json - Safe defaults: no network, no shell, no file-write, approve-dangerous, 30s timeout, 8 calls/turn, audit on
harness mcp-scan <path>— "npm audit for agent tools": static-only scan flagging shell/network grants, missing audit/timeouts, wildcard permissions, unguarded secrets, unpinned deps. Exits 1 on any HIGH.
Verticals (19 quick-start templates)
npx metaharness --list
npx metaharness my-bot --template vertical:coding
Each ships bespoke domain agents (with system prompts), skills, commands, and per-host settings — all default-deny.
One-command examples
Don't want to pick flags? Each host and vertical has a dedicated
@metaharness/* wrapper — published, one npx away, no template/host
flags to remember. A scaffold from a wrapper is byte-identical to the
equivalent metaharness invocation.
Host integrations
Vertical workflows (ready-made multi-agent pods)
All 18 are live on npm under @metaharness. Source + per-package README:
examples-packages/ · plain-language deep-dive gists:
examples-packages/GISTS.md.
Day-to-day commands
After scaffolding, every harness has a harness CLI:
21 subcommands total. Every one respects --help / -h. Shell completion: harness completions bash | zsh | fish.
📖 Full reference: docs/USAGE.md
Status
v0.1.x beta — published and usable, with the credibility/doc reconciliation in issue #4 / ADR-042 in progress. The release pipeline is mature: CI matrix green across Rust × 3 OS + WASM × 3 OS + Node 20+22 × 3 OS + Bench + pack+install × 3 OS
- a CI-passed aggregator; single-command releases (
node scripts/release.mjs <bump> --push) atomically bump 15 sources, run all gates, and tag.
Architecture in 30 seconds
You (harness author)
└→ agent-harness-generator ← the factory
└→ Your harness (.zip) ← what you ship
├ npx <your-name> ← your identity
├ <your agents> ← your content
└ @metaharness/kernel ← shared primitives (Rust + WASM + NAPI-RS)
└→ Host adapter (Claude Code / Codex / pi.dev / Hermes / OpenClaw / RVM)
└→ LLM providers
You operate the factory. The factory produces your harness. Your users never see the factory — only the brand and CLI you ship. The kernel ships as @metaharness/kernel (Rust → wasm-pack + NAPI-RS); your content stays yours.
📖 Deeper: docs/ARCHITECTURE.md · docs/adrs/INDEX.md (220 ADRs)
Quality gates
Developer quick-start
git clone https://github.com/ruvnet/metaharness
cd metaharness
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
npm install
npm run build:wasm
npm test
node scripts/healthcheck.mjs
See CONTRIBUTING.md.
Related
- ruflo — the meta-harness this generator factors apart
- ruvector — vector + agentic database (memory backend)
- @ruvector/emergent-time — memory-decay clock the kernel uses
Cost-Pareto Leaderboard
→ Live leaderboard — the cost-performance Pareto frontier
Which harness resolves the most benchmark per dollar, not just the highest raw score — ranked by a tunable
Value Score that blends capability and price. Tabs: SWE-bench Lite / Verified / Pro / DRACO /
SWE-ultralite (a fast n=25 model×mode scouting map). Every Darwin row is fully conformant (the solver never
sees gold tests during solving) and measured with the official swebench Docker harness, with Wilson 95% CIs.
Latest validated, conformant results (2026-06-26):
The same cheap→frontier empty-patch cascade (escalate only the empties to Opus) measures 55.6% on the full
SWE-bench Verified (500) — official swebench gold eval, conformant, ~56× cheaper than frontier-only — which
beats the Lite cascade (51.3%); the pattern generalizes across both splits. SWE-bench Verified cost is an
estimate (per-instance cost not captured in predictions). LiveCodeBench (n=100, contamination-resistant
post-cutoff window) lifts 44% → 62% via cost-cascade; caveats are honest: deepseek snapshot cutoff unpinned,
part of the lift is run-to-run variance (clean attributable lift +8 on the escalated tail), n=100 is directional
(not 1:1 with the official whole-release ~34%). Details in
packages/darwin-mode/bench/results/RESULTS.md (§33) and
LEARNINGS.md (§46b/§47).
Run your own harness and put it on the board — fork, add a measured row, open a PR. Conformance rules, the entry schema, and a step-by-step walkthrough are in SUBMISSIONS.md.
License
MIT — see LICENSE.
FAQ
What is MetaHarness?
MetaHarness is a CLI and browser Studio that turns any GitHub repo (or a
blank slate) into a custom AI agent harness. The output is a branded,
npm-publishable package with its own npx <name> CLI, MCP server, memory,
governance policy, and Ed25519 witness-signed releases. Runs on ten hosts:
Claude Code, Codex, pi.dev, Hermes, OpenClaw, RVM, Copilot, OpenCode,
GitHub Actions, and Prime Agent.
How is MetaHarness different from an agent framework?
Frameworks help developers build agents. MetaHarness helps repositories ship agents. The model is replaceable; the harness is the product.
Do I need to run a server?
No. The Studio is 100% client-side (GitHub Pages). The CLI runs locally. There is no MetaHarness account, no hosted backend, no telemetry.
Does it execute my code during analysis?
No. metaharness analyze and metaharness genome are deterministic
static-analysis only. Inferred build/test commands are marked
trust: inferred · execution: disabled.
Which agent runtimes does it support?
Ten today: Claude Code, Codex, pi.dev, Hermes, OpenClaw, RVM, Copilot, OpenCode, GitHub Actions, Prime Agent.
What languages does it understand?
Rust, TypeScript / JavaScript, Python, and Go are detected deterministically via lockfile and manifest probing. Lexical scoring is the default; optional in-browser MiniLM embeddings via Transformers.js boost recall for unusual repos.
Is the output really npm-publishable?
Yes — the generated harness ships with package.json, bin, a working
CLI, and harness validate to gate releases. harness sign adds the
Ed25519 witness; harness sbom emits SPDX-2.3.
Keywords: metaharness, AI agent CLI, AI agent scaffold, AI agent generator, repo to agent, GitHub repo to AI agent, agent harness, agent harness generator, agent framework alternative, agentic AI, agentic workflow, autonomous AI agents, multi-agent framework, multi-agent system, MCP, MCP server, model context protocol, Claude Code plugin, OpenAI Codex plugin, Anthropic agents, GPT agent, Codex agent, pi.dev extension, hermes agent, Nous Research, OpenClaw, RVM agent, vertical AI agents, custom AI CLI, npx metaharness, npm create AI agent, Rust WASM agent kernel, NAPI-RS, wasm-bindgen, agent memory, ReasoningBank, HNSW vector search, emergent time, witness manifest, Ed25519 signed, provenance, SBOM, SPDX, SLSA, plugin marketplace, IPFS registry, drift detection, anti-slop, TDD agents, self-evolving agents, federated agents, swarm intelligence, GCP Workload Identity Federation, Secret Manager, npm provenance, repo-aware AI, repo-native CLI, repo factory.
