ruvnet/metaharness: scaffolding a branded agent harness from any repo

The problem MetaHarness addresses: every repo gets the same generic agent

A coding agent dropped into an unfamiliar repository starts from nothing. It does not know the file layout, the build commands, the release process or which directories are dangerous to touch. Teams work around this by writing project instructions by hand, then maintaining them as the repo changes. MetaHarness treats that maintenance as a generation problem. Its README states the premise directly: "Every serious repo deserves its own agent," and describes the tool as "a factory for agent frameworks" rather than another agent framework. The audience is therefore narrow and specific. It is for maintainers who already use a host such as Claude Code, OpenAI Codex, pi.dev, Hermes, OpenClaw or RVM, and who want the harness around the model to be scoped to one project. The model stays replaceable; the generated harness is the artifact you keep.

What the generator actually emits

The output is not a running service. It is a package: the README describes an npm-publishable .zip carrying your branding and your own npx <your-name> CLI. Alongside the CLI, a scaffold includes recommended agents, skills, slash commands and MCP tools, a scoped memory namespace, and a governance policy. Release verification and witness-signed provenance are part of the same bundle. The repository layout matches this: packages/ holds the individual generators, crates/ holds Rust components including a kernel, and examples/ contains quickstart, multi-host, federation, host-tour and vertical-tour directories. The workspace root package.json is private and named agent-harness-generator, with the published CLI living under the metaharness name and the library under @ruvnet/agent-harness-generator. That split matters when you decide what to depend on: the library is the programmatic surface, the CLI is the interactive one.

Host targeting, and the fail-closed case for Prime Agent

A generated harness is not host-neutral in practice. The README lists Claude Code, OpenAI Codex, pi.dev, Hermes, OpenClaw, RVM and Prime Agent as targets, with Prime Agent described as the tenth host, selected by --host prime-agent. The Prime Agent path is the most instructive because the documentation is explicit about its own limits. Prime Agent has no MCP, so the generator emits tools as project-scoped Python-backed skills under .prime/agent/skills/ plus an install runbook. More importantly, Prime Agent cannot enforce a deny-list itself. Rather than silently dropping that part of your security posture, a non-empty deny-list causes the scaffold to ship a SANDBOX-REQUIRED.md file. That is a deliberate fail-closed choice, and it is the kind of behaviour worth checking for in other host adapters before you assume a generated policy is enforced everywhere.

Installing and running a first scaffold

The README gives the CLI as a single npx invocation, and the Studio as a browser alternative that runs locally. Start with the score command, which the README says reads the repository without executing it and prints a report card covering harness fit, build likelihood, tool safety and rough cost per run.

npx metaharness score <repo>

Replace <repo> with the GitHub URL you want assessed. You should get a one-screen report before any files are generated. To generate, the README's headline command is the bare invocation, which opens the interactive path.

npx metaharness

If you are targeting Prime Agent specifically, the host flag is passed at generation time.

npx metaharness --host prime-agent

The README states that this emits skills into .prime/agent/skills/ and an install runbook. Watch for SANDBOX-REQUIRED.md in the output when your policy includes a deny-list. Darwin Mode is wired into every scaffold by default, and the README gives --no-darwin as the way to skip it. The evolve step is a script inside the generated package, not a MetaHarness command.

npm run evolve

The README describes this as mutating the harness config, testing each change in a sandbox, and keeping only changes that measurably improve results, with no network and no API key required.

Darwin Mode and AVO: two different autonomy stories

The README separates two mechanisms that are easy to conflate. Darwin Mode, in @metaharness/darwin, mutates the harness configuration and keeps improvements, with the model held frozen. The documentation says it was validated on SWE-bench Lite bug-fixing. AVO, in @metaharness/avo, is a different thing: an agent that inspects, edits, executes real tools, evaluates, repairs or reverts, branches, consults structured RVF memory and commits, while MetaHarness retains capabilities, budgets, promotion, quarantine, rollback and signed replay receipts. The README states that simple work stays on Darwin's fast path. The claim boundary is unusually explicit. The documentation says the runtime has a deterministic 205-action RVF interruption proof, but that the stronger AVO-class claim remains blocked on a preregistered 100-task unseen SWE-bench gate in ADR-251, and that ADR-253 enforces the boundary at publication against the tag SHA and npm tarball. Treat those ADRs as the authoritative source, not the README summary.

Where the documentation is thin or the tool is the wrong choice

The README does not document rollback for a generated harness, nor does it describe how to uninstall or migrate one after you have published it under your own npm name. That is a real gap for anyone treating the output as production infrastructure. The experimental packages carry their own warnings. The ARC-AGI-3 packages are described as private and experimental, with no ARC performance claim made until an official closed scorecard satisfies the frozen controlled-ablation gate in ADR-254. The README reports a single-game smoke result favoring AVO 3.2676 to 0.3968 but states plainly that the non-competition result is not claim-eligible. The field-memory package is described as experimental, single-process by default, with its RuVector adapter failing closed unless a corrected flat-index wrapper is used. If your need is a general agent framework to build an application on, this is the wrong layer: MetaHarness generates harnesses, it does not replace the host that runs them. And if you require a stable, non-experimental surface across every listed package, the repository does not offer one today.

Alternatives and the actual difference in approach

The obvious alternative is to skip generation and hand-write project instructions for your existing host. That is cheaper for a single repository and needs no new dependency, but it does not produce a CLI, an MCP server, a memory namespace or release provenance, and it drifts as the repo changes. A second alternative is to adopt a full agent framework and configure it per project. That gives you a supported runtime and a documented extension model, at the cost of carrying the framework's abstractions into every repository. MetaHarness inverts the direction: the host stays, and the per-repo artifact is generated and can be published under your own name. The trade is that you now own a generated codebase, including its governance policy and its release gates, and the README's coverage of maintaining that codebase over time is limited.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-10. Release v0.4.4 is dated 2026-08-10 and is described as a catch-up release covering Darwin evolution, the Flywheel, security hardening and 115 PRs since v0.1.3. An earlier release, v0.1.3 from 2026-06-14, is noted for every scaffold shipping .claude-plugin/plugin.json, which tells you the generated output format has changed between releases. Expect to regenerate or patch scaffolds across minor versions. The licence is MIT at the repository level, and the Cargo workspace also declares MIT. That is permissive, but it governs the generator, not necessarily the provenance or signing components you attach to your own releases, and the README does not spell out those implications. Nothing here is legal advice; read the LICENSE file and the individual package manifests before you publish.

Editorial conclusion

Adopt MetaHarness if you want a repo-scoped agent harness with its own CLI name and MCP server, and you are willing to treat the generated output as a starting point rather than a finished product. Skip it if you need a general agent framework to build against directly, or if you cannot tolerate experimental packages sitting alongside the stable scaffold path. Before committing, run npx metaharness score against your repository, then read docs/USERGUIDE.md and the ADR files that back any claim you intend to rely on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ruvnet/metaharness on GitHub