by ruvnet
Generate a custom AI agent harness for any repository, delivering a branded npx CLI, scoped memory, governance policy, witness‑signed releases, and support for multiple agent hosts.
MetaHarness provides a factory that mints a full‑featured, repo‑aware AI agent harness. It turns a GitHub repository (or a blank project) into a publishable npm package containing its own CLI, MCP server, memory namespace, governance rules, and provenance signatures. The harness can run on ten different agent hosts such as Claude Code, OpenAI Codex, pi.dev, Hermes, OpenClaw, RVM, GitHub Copilot, OpenCode, GitHub Actions, and Prime Agent.
npx metaharness my‑bot --template vertical:coding --host claude-code
cd my‑bot && npx . --help
npx metaharness --wizard
harness sub‑command suite (e.g., harness doctor, harness validate, harness score, harness upgrade).npx @your‑org/your‑harness.@metaharness/router) that selects the cheapest model meeting quality thresholds.Q: Do I need to run a server to use the generated harness? A: No. The harness runs locally via the provided CLI. A local MCP server is bundled and started automatically when needed.
Q: Will my code be executed during analysis?
A: No. All repository analysis (metaharness analyze-repo or harness genome) is static‑only and deterministic.
Q: Can I choose which LLM provider to use?
A: Yes. Select a host at generation time (e.g., --host claude-code) or switch later by installing the corresponding @metaharness/* wrapper.
Q: How does governance work? A: The generated MCP policy defaults to deny all network, shell, and file‑write operations unless explicitly allowed. Policies are editable and audited.
Q: Is the output truly publishable to npm?
A: Absolutely. The scaffold includes a complete package.json, binary entry point, signing workflow, and SBOM generation, ready for npm publish.
Q: What languages does MetaHarness understand? A: It detects Rust, TypeScript/JavaScript, Python, and Go projects via lockfiles and manifests.
Q: How is provenance ensured? A: Each release is signed with an Ed25519 witness and the package is published with SLSA L2 provenance.
Q: Can I run the harness on CI/CD?
A: Yes. The GitHub Actions host generates a non‑interactive workflow (.github/workflows/) with default‑deny permissions.
Q: Is there a cost‑performance leaderboard? A: A live Pareto leaderboard is available at https://ruvnet.github.io/metaharness/cost-pareto.html, showing benchmark results versus cost.
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
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.
In under 60 seconds, in your browser, with nothing leaving your machine:
Output is an npm-publishable .zip with your name on it, your branding, your npx <your-name> CLI.
@metaharness/darwin/contrastive adds scoped proposals, actual probes, selective composition and metered experiment memory behind immutable caller policy. API guide. Independent paired confirmation adds unseen-task, statistical and regression checks. Public intent-classification evidence remains separate from general agent performance claims.Watch Darwin evolve a harness · Explore model routing · Review experimental extensions
@metaharness/arc-agi-3 owns exact observations,
persistent evidence-backed memory, belief-state exploration, guarded actions,
supervisor interventions, checkpoints, and hash-chained receipts.
@metaharness/arc-agi-3-chatgpt exposes 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 an OPENAI_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.@metaharness/avo lets 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.@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 SANDBOX-REQUIRED.md instead of silently dropping
your posture. From its design we also shipped RefineMutator — an evidence-backed proposer in
@metaharness/darwin that must cite the
failing traces behind each edit or propose nothing — and an opt-in --sessions 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 deferred behind a pre-registered A/B in
evals-toolcall. See ADR-246 /
ADR-247. ($0)npx metaharness score <repo> reads
the repo (never runs it) and prints a one-screen report card — how well a
harness fits, how likely it is to build, how safe the tools are, and the
rough cost per run — so you know what you'll get before scaffolding.@metaharness/router
routes each request to the right model from your own results — same quality,
far less spend. Works out of the box with zero native deps; train it on your
data for a sharper fit (npm i @metaharness/router). Add the optional
@ruvector/tiny-dancer
to train a fast native model instead — same training data, no API change.@metaharness/field-memory is an experimental,
single-process-by-default packed-attractor layer with verified outcome caps,
support quarantine, decay, cost-aware choice, and no raw-episode API. Its
RuVector adapter fails closed unless a corrected flat-index wrapper is used.@metaharness/darwin) wired in —
run npm run evolve and the harness mutates its own config, tests each change in a
sandbox, and keeps only what measurably improves. The model stays frozen; the harness
evolves. Safe by default (no network, no API key; pure refactor/tuning behind a safety
gate). Validated on real SWE-bench Lite bug-fixing. --no-darwin to skip.--field-memory to scaffold a small bootstrap around the forthcoming
@metaharness/field-memory@^0.1.0 package. The generated harness uses packed
attractors, three distinct verifier-derived principals for support, no
hysteresis, and a bounded drift window. Principal independence depends on the
verifier's identity system.
It will not open storage or accept shared updates until the deployment
supplies an absolute storage path, a compatible adapter, and a principal
verifier backed by deployment authentication. Package influence caps are
centroid-local; fleet-wide admission and rate limits belong in that verifier.
The RuVector adapter requires a configuration-verified, in-place FlatIndex
with cosine distance and rejects HNSW or unverified legacy stores.
Minimum support quarantines routing but does not make stored singleton
aggregates confidential; protect field snapshots and registry storage.
A deployment-secret identity hash key of at least 32 bytes is also required
and must survive state restore. Conflicting package declarations or an
existing field module fail before disk writes, and harness upgrade reapplies
the opted-in overlay only after validating its exact, versioned manifest
contract. Unsupported overlay schemas require an explicit migration.
storage.writerScope: process requires one writer service; multi-process or
fleet use requires distributed. The flag is off by default, so existing
scaffold output is unchanged.@metaharness/weight-eft, metaharness weight-eft) takes the
complementary lever to Darwin's gradient-free evolution: it exports the harness's gold-resolved
archive into standard SFT/DPO sets and LoRA-tunes the open cheap tier (GLM/Qwen), so the
cost-cascade escalates to Opus/GPT less often. It attacks cost (fewer 0 / GPU-gated.)A generated harness is a starting point you own, not a fixed framework. Open it and make it yours:
harness doctor / harness validate keep it healthy as you trim.npm publish — now anyone on your team runs
npx @your-org/your-harness and 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.
# 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 →
The same harness output runs on ten agent hosts — nine interactive, plus GitHub Actions (CI/CD):
| Host | What ships | Notes |
|---|---|---|
| Claude Code | MCP server + hooks + 3-scope settings | Richest surface; Ruflo-native |
| OpenAI Codex | MCP via ~/.codex/config.toml |
TOML, no hooks |
| pi.dev | Pi extension via pi.registerTool() |
No MCP by design |
| Hermes | MCP runtime, <think> scrubbing |
Per Hermes issue #741 |
| OpenClaw | ~/.openclaw/openclaw.json + workspace skills |
Personal-AI gateway |
| RVM | Bare-metal microhypervisor + capability tokens | Hardware isolation for untrusted peers |
| GitHub Copilot | MCP via .vscode/mcp.json |
VSCode 1.99+ (ADR-032) |
| OpenCode | MCP via .opencode/opencode.json |
sst/opencode TUI (ADR-036) |
| Prime Agent | .prime/agent/ skills (Python-backed, no MCP) + install-prime-agent.md |
Fail-closed sandbox posture (ADR-247) |
| GitHub Actions | .github/workflows/ + composite action.yml |
Non-interactive CI/CD; default-deny via permissions: (ADR-033) |
See ADR-004 — Host integration model and ADR-033 — GitHub Actions host.
MCP is included as a first-class adapter surface, not the identity. It is gated and default-deny (ADR-022):
off · local (stdio) · remote (HTTPS + auth)src/mcp/{server,tools,resources,prompts,policy,audit}.ts + a scannable .harness/mcp-policy.jsonharness 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.npx metaharness --list
npx metaharness my-bot --template vertical:coding
| Category | Templates |
|---|---|
| Starter / Operations | minimal, vertical:devops |
| Engineering | vertical:coding, vertical:ai, vertical:repo-maintainer (iter 113) |
| Knowledge | vertical:research, vertical:ruview, vertical:education |
| Finance / Pro | vertical:trading, vertical:legal, vertical:health |
| Customer / Growth | vertical:support, vertical:crm, vertical:marketing, vertical:advertising, vertical:sales |
| Business / Frontier | vertical:business, vertical:agentics, vertical:gaming, vertical:exotic |
Each ships bespoke domain agents (with system prompts), skills, commands, and per-host settings — all default-deny.
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.
After scaffolding, every harness has a harness CLI:
| You're trying to … | Subcommand |
|---|---|
| Smoke-check the scaffold | harness doctor |
| Run every release gate | harness validate |
| Check kernel ↔ harness compatibility | harness diag |
| Score the harness 0-100 with badges | harness score |
| Pre-scaffold: is this REPO ready for an agent? | harness genome <repo> |
| Pre-scaffold: fit/cost/safety report card for a repo | metaharness score <repo> |
| MCP threat-model artifact for a PR review | harness threat-model |
| Declare OIA v0.1 layer alignment | harness oia-manifest |
| File a useful support ticket | harness diag --bundle > bundle.json |
| Diff two harnesses | harness compare a/ b/ |
| Share MCP + Bash + claims config for review | harness export-config |
| Run npm-audit per-harness | harness audit --bundle > audit.json |
| Emit SPDX-2.3 SBOM | harness sbom |
| Drift-detect against the latest template | harness upgrade |
| Sign / verify the witness | harness sign · harness verify |
| Pin the manifest to IPFS | harness publish --confirm |
| Recommend a harness from a repo | harness analyze-repo |
21 subcommands total. Every one respects --help / -h. Shell completion: harness completions bash | zsh | fish.
📖 Full reference: docs/USAGE.md
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
node scripts/release.mjs <bump> --push) atomically bump 15 sources, run all gates, and tag.| Layer | Status |
|---|---|
| Rust kernel (WASM + NAPI-RS) | Shipped — 7 subsystems |
| 10 host adapters | claude-code · codex · pi-dev · hermes · openclaw · rvm · copilot · opencode · github-actions · prime-agent |
17 harness subcommands |
Shipped |
| 7 Codex skills | Shipped |
| Claude marketplace plugin | Shipped + schema-validated |
| Witness signing (Ed25519) | Shipped + tamper-tested |
| MCP tool dispatch | 11 end-to-end cases |
| Test suite | 2,254 passing across 246 files (CI green on main) |
| CI matrix | 16 jobs green |
| Security pipeline | cargo-audit · cargo-deny · npm-audit · CodeQL · SBOM (SPDX-2.3) |
| Publish pipeline | GCP WIF + 2 gates + 11 packages + IPFS pin |
| Agent Harness Studio | Live at https://ruvnet.github.io/metaharness/ |
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)
| Concern | Where |
|---|---|
| CI | ci.yml — Rust 3-platform × fmt/clippy/test/doc + WASM build + size budget + Node 20/22 × 3-platform |
| Publish | publish.yml — GCP WIF → Secret Manager → smoke → npm publish --provenance (SLSA L2) |
| Security | security.yml — cargo-audit + cargo-deny + npm-audit + CodeQL + weekly cron |
| Provenance | ADR-011 — Ed25519-signed witness manifest, byte-deterministic across runners |
| Studio liveness | pages-monitor.yml — daily HTTP probe of live Studio |
| Research quality (DRACO) | draco.yml — cross-domain deep-research benchmark (ADR-037). Deterministic subset gates the scorer/runner machinery on every push (offline); a weekly judged cadence runs the real OpenRouter-fusion score. 5 dimensions (grounding/coverage/balance/cleanliness/faithfulness); the verifier + judge are different model families than the synthesizer (fusion). See packages/bench/draco/. |
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.
→ 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):
| benchmark | config | resolve | n | Wilson 95% CI | cost |
|---|---|---|---|---|---|
| SWE-bench Verified | GLM→Opus empty-patch cascade | 55.6% (278/500) | 500 | [51.2, 59.9] | ~$0.15/inst (est.) |
| SWE-bench Lite | GLM→Opus empty-patch cascade | 51.3% | 300 | — | ~$0.27/inst |
| LiveCodeBench (release_v5 ≥2024-12-01) | single-shot | 44% | 100 | — | — |
| LiveCodeBench (release_v5 ≥2024-12-01) | cost-cascade | 62% | 100 | — | — |
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.
MIT — see LICENSE.
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.
Frameworks help developers build agents. MetaHarness helps repositories ship agents. The model is replaceable; the harness is the product.
No. The Studio is 100% client-side (GitHub Pages). The CLI runs locally. There is no MetaHarness account, no hosted backend, no telemetry.
No. metaharness analyze and metaharness genome are deterministic
static-analysis only. Inferred build/test commands are marked
trust: inferred · execution: disabled.
Ten today: Claude Code, Codex, pi.dev, Hermes, OpenClaw, RVM, Copilot, OpenCode, GitHub Actions, Prime Agent.
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.
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.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
An MCP server implementation that provides a tool for dynamic and reflective problem-solving through a structured thinking process.
by zylon-ai
Provides an open-source API layer that enables local OpenAI‑compatible models to be used for production AI applications, offering standardized message handling, document ingestion, retrieval‑augmented generation, tool integration, and MCP connectivity.
by danny-avila
Provides a self‑hosted ChatGPT‑style interface supporting numerous AI models, agents, code interpreter, image generation, multimodal interactions, and secure multi‑user authentication.
by block
Automates engineering tasks on local machines, executing code, building projects, debugging, orchestrating workflows, and interacting with external APIs using any LLM.
by RooCodeInc
Provides an autonomous AI coding partner inside the editor that can understand natural language, manipulate files, run commands, browse the web, and be customized via modes and instructions.
by pydantic
A Python framework that enables seamless integration of Pydantic validation with large language models, providing type‑safe agent construction, dependency injection, and structured output handling.
by mcp-use
A Python SDK that simplifies interaction with MCP servers and enables developers to create custom agents with tool‑calling capabilities.
by lastmile-ai
Build effective agents using Model Context Protocol and simple, composable workflow patterns.
by Klavis-AI
Provides production‑ready MCP servers and a hosted service for integrating AI applications with over 50 third‑party services via standardized APIs, OAuth, and easy Docker or hosted deployment.