The harness is
the product.

First, the short version of what it is, so the rest makes sense. A harness is the wrapper around an AI model — not the model itself. Underneath you are still talking to Claude, GPT, or whatever model you use. The harness is the bit that gives your assistant a name, knows your project, carries a set of skills, and keeps a safety net around what it is allowed to do. MetaHarness is a factory that builds those wrappers. As the project puts it: “It is not another agent framework. It is a factory for agent frameworks. The model is replaceable. The harness is the product.”

So why build a factory instead of just one more assistant? Because of a trap the makers hit themselves. Their earlier product, ruflo, came as one big bundle — a small core engine welded to 60+ pre-made agents, 30+ skills, and 33 plugins, all fused together. People loved the engine but wanted their own brand, their own agents, and their own listing. The only way to get that was to copy (“fork”) the whole bundle — and the moment you did, you were cut off from every future update to the engine. That is a one-way door: rebrand once, and you are frozen in time.

MetaHarness was built to take the hinges off that door. It separates the reusable engine from the opinionated content, so you can take just the engine and generate just the pieces you actually want — owned and branded by you, and still able to pull future engine updates.

There are three everyday headaches it removes:

1. Lock-in. As above — copying a bundled product just to rebrand it means you give up every future update to the part you actually relied on. You get stuck.
2. Too many places to run an assistant. Claude Code used to be the obvious home for AI agents. Now there are several — Codex, Hermes, pi.dev and more — and each one wants its config files set up its way. (Config = the small settings files that tell a tool how to behave.) Setting the same assistant up by hand for each place is tedious and easy to get wrong. MetaHarness writes the right files for whichever places you pick.
3. Rebuilding the same plumbing every time. Roughly 80% of any new agent project is the same unglamorous wiring done over again: a local tool server, a place to keep memory, the rules for what is allowed, and a way to sign your release so people can trust it. MetaHarness generates all of that for you, correctly, in one go.

In plain terms: instead of spending your first week rebuilding scaffolding, you answer a few questions and get a clean, safe starting point that is already yours.

A factory only pays off once there is enough variety for it to produce. Two things just crossed that line.

The homes for AI agents multiplied. A year or two ago you mostly ran assistants in one place. Now Codex, Hermes, pi.dev and others each have their own way of running agents. A factory that can target any of them — without you rewriting anything — is suddenly worth having.

The plugin marketplace woke up. A “plugin” is just an add-on capability you can drop into your assistant. There is now a shared, open registry of these (hosted on IPFS, a decentralised file network), so a harness you build can both pull in ready-made plugins and, if you want, publish its own. Building becomes assembling from parts rather than carving everything from scratch — which is exactly when an assembly line earns its keep.

It walks you through a short series of choices — call it the composer — and then assembles a complete, self-contained package from your answers. You can answer the questions in a friendly picker (a “wizard”) or, if you prefer, pass the same answers as command-line options. Either way you end up at the same place. The steps, in order, are:

1. Identity — the name, the package scope, a description, a licence, and who the author is.
2. Hosts — tick which places you want it to run (Claude Code, Codex, and so on). Pick at least one.
3. Primitives — switch the engine’s building blocks on or off: the tool server (always on), automations, memory, smart routing, the marketplace hook, and signed provenance. All on by default.
4. Agents — choose helpers from a curated list (it suggests a coder, a reviewer, and a tester to start).
5. Skills — reusable abilities you can bolt on.
6. Plugins — optional add-ons from the shared registry (none by default).
7. Features — opt-in extras like teamwork between agents or self-improvement.
8. Branding — “powered-by” mode or fully independent, plus your brand wording.
9. Confirm — a clear summary: every file it will create, the exact engine version it pins to, and a size estimate, before anything is written.

Two things make this safe and predictable. It never runs your code — when it looks at a repo it only reads the file list and a few text files to make suggestions; it does not execute anything. And the generated tool server starts locked down (“default-deny”): no internet access, no shell, no writing to files, until you explicitly allow each one. Nothing is on that you did not turn on.

A note so the numbers add up: the teaching walkthrough on this page uses seven questions (the 7 stages of understanding, sections 01–07). The tool’s own composer has the nine build steps listed just above. They are different lists for different jobs — don’t worry if the counts differ.

When it has done its job, you have a single, self-contained package — say you called it my-bot — that includes:

• Its own npx my-bot command, branded as yours, not as someone else’s tool.
• Its own local tool server, locked down by default.
• Its own private memory space, kept separate from everything else.
• The agents, skills, plugins, and per-place config files you chose.
• A signed receipt of exactly what is inside it (a cryptographic signature called an Ed25519 witness manifest), so anyone who installs it can confirm they got precisely what you shipped — nothing swapped or added.

You can publish it (npm publish) and your users run npx my-bot init. They never see the factory underneath — only your brand.

And it does not have to stand still. A finished harness can be set to quietly improve its own settings over time: it tries a small tweak, tests it safely in a sandbox, and keeps the change only if it measurably helped. The AI model never changes — only the wrapper gets a little better. (More on this in the use cases below.)

Honest maturity note: this is v0.1.x beta — published and usable, but still settling. The README badge shows 568 tests passing; you may see slightly different totals in other docs as they catch up, so treat 568 as “the headline figure,” not gospel.

There are two ways in, and they give the same result — a .zip (or scaffolded folder) that is yours to keep.

1. In your browser, with nothing to install. Open the Studio at ruvnet.github.io/agent-harness-generator, pick a tab (turn a repo into a harness, create one from scratch, add a skill or agent, or verify a harness), make your choices, and click Download .zip. Then on your own machine:

unzip my-bot.zip
cd my-bot
npm install

The Studio runs entirely in your browser. For analysis it only reads a repo’s public file list through GitHub’s API — it never reads your file contents on a server, and there is no account, no sign-in, and no tracking.

2. In your terminal, if you live there. The same behaviour, from the command line:

npx metaharness my-bot --template vertical:coding --host claude-code
# or be asked the questions instead:
npx metaharness --wizard

After scaffolding, the files are yours: open them, delete what you don’t need, adjust the wording and the routing, and when you’re happy, ship it with npm publish --provenance (the --provenance part attaches that signed receipt so installers can trust it).

One naming note so nothing trips you up: the published command is npx metaharness. In some older docs you may see npx create-agent-harness — that is the same tool under its internal package name, not a second product. Lead with metaharness.

Prefer the terminal? If you’re not sure what to pick, run the wizard. It asks just four things — a name, a template, where it will run, and a one-line description — and then prints the exact npx metaharness … command it would have run, so you can skip the questions next time:

npx metaharness --wizard

Already know what you want? Jump straight in:

npx metaharness my-bot --template vertical:coding --host claude-code
cd my-bot && npm install && npx . --help

Want to see what’s on the menu first? npx metaharness --list shows every template. And once your harness exists, run harness doctor — a quick health check that confirms the scaffold is set up correctly before you go further.

That’s the whole on-ramp: browser Studio or one terminal command, four questions, a working package. The use cases below show where to take it next.

Every command below is taken straight from the project’s own docs — nothing here is made up. Pick the one that sounds like you.

Everything on this page also comes as one download with two halves. One half is for you — a short written primer, plus a studio/ folder with a NotebookLM audio overview and a deep-dive report. The other half is for your AI — a small, searchable knowledge pack your assistant can read so it can answer questions about MetaHarness accurately, with sources, instead of guessing.

Wiring the AI half into Claude Code takes three small steps:

1. Unzip it next to your project.

   unzip metaharness-dropin.zip
   cd metaharness-dropin/for-ai
   npm install

2. Point Claude Code at it with a .mcp.json file. This tiny file tells Claude Code about the local knowledge tool. Drop it in your project root:

   {
     "mcpServers": {
       "metaharness-kb": {
         "command": "node",
         "args": ["metaharness-dropin/for-ai/kb-mcp-server.mjs"]
       }
     }
   }

   (.mcp.json is just a list of helper tools Claude Code is allowed to call. Here it registers the knowledge pack as a tool named metaharness-kb.)
3. Add a verification gate to your CLAUDE.md. CLAUDE.md is the instruction file Claude reads first. This line forces it to check the knowledge pack before answering, rather than guessing:

   ## MetaHarness questions
   Before answering ANY question about MetaHarness, query the
   `metaharness-kb` tool and ground your answer in what it returns.
   If the pack has no answer, say so plainly — do not invent one.

Then confirm it works. Ask Claude Code a question only the pack can answer, for example:

What are the nine composer stages in MetaHarness, in order?

If the wiring is right, the answer comes back grounded in the knowledge pack — Identity, Hosts, Primitives, Agents, Skills, Plugins, Features, Branding, Confirm — with the source it drew from. If you instead get a vague reply with no source, the gate isn’t firing: re-check the .mcp.json path and the CLAUDE.md line above.