Related Pages

Related topics: System Architecture & Kernel, Templates, Hosts & Plugin Manifests

Introduction & Quick Start

metaharness is an opinionated scaffolding and orchestration toolkit for building AI coding agents. It packages reusable "harness" templates — pre-configured collections of prompts, skills, hooks, and tool integrations — so that teams can stand up a Claude Code–compatible agent workspace in seconds rather than assembling one from scratch. The project ships two coordinated packages: metaharness (the user-facing CLI) and @ruvnet/agent-harness-generator (the programmatic scaffold engine). Source: README.md:1-20

What is a Harness?

A harness is a self-contained agent workspace. It bundles system prompts, slash-command definitions, tool/hook configuration, and project conventions into a directory that Claude Code (or any compatible runtime) can load directly. Every scaffold produced by metaharness is a working plugin: from v0.1.3 onward, 20/20 templates ship a .claude-plugin/plugin.json manifest, so the directory can be invoked with claude -p --plugin-dir <harness> immediately after generation. Source: README.md:21-40

The repository exposes a catalog of templates (ranging from minimal to feature-rich, domain-specific stacks) so that users can start from a known-good baseline instead of writing every prompt and hook by hand.

Installation

The CLI is distributed as the npm package metaharness. It can be invoked without a global install via npx, or installed once per machine:

# Run without installing
npx metaharness --help

# Or install globally
npm install -g metaharness

The published package wraps a thin entry point that delegates to the generator library. Source: packages/create-agent-harness/package.json:1-30 The bin field maps the metaharness command to the compiled dist/bin.js entry. Source: packages/create-agent-harness/src/bin.ts:1-15

Quick Start Workflow

The typical first-run experience is a single command that scaffolds a new harness into the current (or a target) directory:

# Create a new harness in ./my-agent
metaharness new my-agent

# Or scaffold into the current directory
metaharness new .

Behind the scenes, the CLI dispatches to main() in bin.ts, which parses subcommands and forwards them to the handler map defined in subcommands.ts. Each handler invokes the generator, copies the selected template into the destination, and emits a .claude-plugin/plugin.json automatically. Source: packages/create-agent-harness/src/subcommands.ts:1-50

A minimal end-to-end session looks like this:

1. Scaffold — metaharness new my-agent copies template files and the plugin manifest.
2. Inspect — review .claude-plugin/plugin.json, CLAUDE.md, and any skill files.
3. Customize — edit prompts, add hooks, or layer in project-specific tooling.
4. Run — launch Claude Code against the harness directory.

CLI Surface and Subcommands

The CLI exposes a small, predictable verb set so that users can navigate the system without memorizing flags. The handler map in subcommands.ts is the authoritative list of supported commands. Source: packages/create-agent-harness/src/subcommands.ts:20-80 Common entries include:

⚠️ Known issue: the compiled dist/bin.js discards main()'s return code, so every subcommand currently exits 0 even on failure — a failed command appears green in CI. Track progress in issue #73. The learn subcommand was the first to receive a scope fix for this behavior in PR #72. Source: packages/create-agent-harness/src/bin.ts:30-60

Programmatic Use

For automation and embedding, the generator is published separately as @ruvnet/agent-harness-generator. Importing it lets scripts compose scaffolds alongside other tooling:

import { generateHarness } from "@ruvnet/agent-harness-generator";

await generateHarness({
  template: "minimal",
  destination: "./out",
  emitPluginManifest: true, // default true since v0.1.3
});

This entry point shares its core implementation with the CLI handlers, so behavior is consistent regardless of whether the user is at a terminal or inside a build pipeline. Source: packages/create-agent-harness/src/index.ts:1-40

Where to Go Next

• New users should read the User Guide for a guided tour of template selection and customization. Source: docs/USERGUIDE.md:1-30
• Power users looking for flags, environment variables, and exit-code semantics should consult Usage. Source: docs/USAGE.md:1-40
• Contributors extending the template catalog start in packages/create-agent-harness/src/subcommands.ts and the template assets shipped alongside the generator.

With a single metaharness new invocation, you get a working, plugin-ready Claude Code harness — and from there, every subsequent change is just editing files in a normal project tree.

Related Pages

Related topics: Introduction & Quick Start, Self-Evolution, Routing & Cost-Pareto

System Architecture & Kernel

Purpose & Scope

metaharness is a Node.js/TypeScript monorepo whose kernel is a scaffolding CLI that materializes *agent harnesses* — opinionated directory layouts consumable by Claude Code via claude -p --plugin-dir <harness>. The "kernel" in this project is therefore not a Rust/crate subsystem (as the example file list in some templates suggests) but the create-agent-harness package: the entry point that resolves a template, copies it onto disk, patches in the user-supplied name, and writes the plugin manifest Source: packages/create-agent-harness/package.json:1-40. Two npm packages form the kernel surface: metaharness (the user-facing CLI shim) and @ruvnet/agent-harness-generator (the generator library) Source: packages/agent-harness-generator/package.json:1-30.

High-Level Architecture

The kernel follows a standard monorepo → package → template hierarchy:

metaharness (repo)
└── packages/
    ├── create-agent-harness/   ← CLI entry & dispatch
    │   ├── src/bin.ts          ← argv → subcommand
    │   ├── src/main.ts         ← core generator
    │   └── dist/bin.js         ← compiled shim
    ├── agent-harness-generator/← reusable generator lib
    └── ... (shared utilities)
└── templates/
    ├── minimal/.claude-plugin/plugin.json
    ├── research-assistant/.claude-plugin/plugin.json
    └── ... (20 templates total post-v0.1.3)

The CLI bin file is intentionally thin: it parses arguments and forwards the call to main(), then exits Source: packages/create-agent-harness/src/bin.ts:1-40. The main() function holds the orchestration logic — template lookup, file rendering, and post-write verification Source: packages/create-agent-harness/src/main.ts:1-120.

Process Flow

A user invocation travels through three distinct layers:

1. CLI shim — dist/bin.js is what npm executes when the user runs npx metaharness. It requires the compiled TS source and invokes main() Source: packages/create-agent-harness/dist/bin.js:1-20.
2. Subcommand dispatcher — src/bin.ts maps argv tokens to actions such as init, learn, list, or update Source: packages/create-agent-harness/src/bin.ts:30-80.
3. Generator core — src/main.ts performs the actual scaffold; it loads a template from templates/<name>/, applies string interpolation, and writes the result Source: packages/create-agent-harness/src/main.ts:40-120.

flowchart LR
    A[user: npx metaharness] --> B[dist/bin.js shim]
    B --> C[src/bin.ts dispatcher]
    C --> D[src/main.ts generator]
    D --> E[templates/* copy & render]
    E --> F[target directory + .claude-plugin/plugin.json]
    F --> G[claude -p --plugin-dir]

Known Kernel Issue: Exit Code Propagation

The most prominent defect currently filed against the kernel is silent exit-code loss in the CLI shim. Issue #73 documents that packages/create-agent-harness/dist/bin.js discards the return value of main(), so every metaharness subcommand reports exit code 0 even when generation fails Source: packages/create-agent-harness/dist/bin.js:1-20. The compiled shim looks roughly like:

require("./main")(process.argv.slice(2));   // return value thrown away

The result: failed init or learn runs look green in CI and in shell pipelines that gate on $?. PR #72 fixed the symptom for the newly introduced learn subcommand but did not propagate the change to the broader kernel Source: https://github.com/ruvnet/metaharness/issues/73. The canonical remediation pattern, present in correct kernel regions, is to forward the promise's resolved value: process.exit(await main(...)) or main(...).then(code => process.exit(code)) Source: packages/create-agent-harness/src/bin.ts:60-75.

Plugin Manifest Kernel (v0.1.3 Milestone)

As of v0.1.3, the kernel guarantees that every scaffolded template ships a Claude Code plugin manifest at <harness>/.claude-plugin/plugin.json Source: templates/*/.claude-plugin/plugin.json:1-20. This is the contract that lets claude -p --plugin-dir <harness> recognize the directory as a first-class plugin rather than as loose files. Release v0.1.3 explicitly highlights that 20/20 templates include the manifest, removing the previous gap where only the minimal template was plugin-ready Source: https://github.com/ruvnet/metaharness/releases/tag/v0.1.3. The manifest typically declares name, version, and an entry command; the kernel renders these from template variables during main() Source: packages/create-agent-harness/src/main.ts:80-110.

Kernel Boundaries

The boundary between create-agent-harness (the CLI wrapper) and @ruvnet/agent-harness-generator (the reusable library) is deliberate: the latter exposes a programmatic API so other tooling can invoke the same template engine without re-implementing rendering logic Source: packages/agent-harness-generator/package.json:15-30.

Operational Summary

• Entry point: npx metaharness <subcommand> → packages/create-agent-harness/dist/bin.js
• Subcommands: dispatched in src/bin.ts and executed in src/main.ts
• Output contract: a target directory containing .claude-plugin/plugin.json consumable by claude -p --plugin-dir
• Open defect: exit-code loss in the shim (Issue #73) — all commands currently exit 0
• Kernel version marker: v0.1.3 ships universal plugin-manifest support across all 20 templates

This architecture keeps the kernel small (CLI + one library), pushes complexity into per-template directories, and standardizes the plugin contract so downstream Claude Code invocations remain stable across template variants.

Related Pages

Related topics: Introduction & Quick Start, System Architecture & Kernel

Templates, Hosts & Plugin Manifests

Overview

The metaharness repository is structured around three cooperating concerns: templates that define the shape of a generated agent harness, host packages that adapt that harness to a specific runtime (Claude Code, Codex, GitHub Actions), and plugin manifests that allow the harness to be loaded as a Claude Code plugin. Together they let a single scaffolded directory be consumed by multiple execution environments without rewriting its contents. The community release v0.1.3 formalised this by ensuring every one of the 20 templates in the catalog ships a .claude-plugin/plugin.json Source: packages/create-agent-harness/templates/catalog.json:1-400.

Template Catalog and Manifests

The template catalog lives at packages/create-agent-harness/templates/catalog.json and is the single source of truth enumerating every scaffoldable harness. Each entry points to a template directory and references a manifest.json that describes the template's identity, intended host targets, and variable substitutions applied at generation time.

A concrete example is the vertical_coding template, whose manifest describes the harness's purpose and the hosts it is compatible with:

Source: [packages/create-agent-harness/templates/vertical_coding/manifest.json:1-60]()

Manifests are consumed by create-agent-harness to:

• Select which files to copy into the target directory
• Resolve placeholder tokens (for example, {{harnessName}}) inside template bodies
• Decide whether the template supports a given host package before offering it to the user

Templates that previously lacked host support (only minimal worked with Claude Code's plugin loader) were unified in v0.1.3, so all 20 catalog entries now ship the plugin manifest described below.

Host Packages

Host packages live under packages/host-*/src/index.ts and provide the runtime adapter that wires a generated harness to a concrete execution environment. Each host is responsible for translating the neutral scaffold into its own invocation conventions, environment variables, and tool-registration surface.

Each host-*/src/index.ts re-exports a small, stable surface that the CLI consumes. The Claude Code host, for example, registers the scaffolded directory so that claude -p --plugin-dir <harness> picks it up directly, courtesy of the plugin manifest described in the next section Source: packages/host-claude-code/src/index.ts:1-80.

The Codex and GitHub Actions hosts perform analogous wiring without requiring the plugin manifest, because those runtimes do not honour .claude-plugin/plugin.json. This is why the manifest is described as Claude-Code-specific, even though the catalog entry for every template now includes it Source: packages/host-codex/src/index.ts:1-80, Source: packages/host-github-actions/src/index.ts:1-80.

Plugin Manifests

A plugin manifest is a small JSON document placed at .claude-plugin/plugin.json inside the scaffolded harness. The template that emits it lives at packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl and is rendered with the same variable substitution engine used elsewhere in the generator:

Source: [packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl:1-30]()

The manifest's primary fields are:

• name — the harness's display name when loaded as a plugin
• version — synchronised with the scaffolded package.json
• description — surfaced by Claude Code's plugin browser
• entry — the command or script Claude Code should invoke when the plugin is activated

Because the manifest is a template (.tmpl), every catalog entry can produce a customised plugin file at generation time without manual editing. The community release v0.1.3 confirmed that 20/20 templates now ship this file, which is what made claude -p --plugin-dir <harness> work uniformly across the catalog Source: packages/create-agent-harness/templates/catalog.json:1-400.

End-to-End Flow

The interaction between catalog, templates, hosts, and plugin manifests can be summarised as:

flowchart LR
    A[catalog.json] --> B[template directory]
    B --> C[manifest.json]
    B --> D[.claude-plugin/plugin.json.tmpl]
    D --> E[rendered plugin.json]
    B --> F[scaffolded harness]
    E --> F
    C --> F
    F --> G[host-claude-code]
    F --> H[host-codex]
    F --> I[host-github-actions]

The catalog selects a template, the template supplies both a manifest and the plugin template, the generator renders the plugin file into the scaffold, and one of the host packages loads the resulting directory into its runtime Source: packages/create-agent-harness/templates/catalog.json:1-400, Source: packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl:1-30.

Community Notes

• v0.1.3 milestone: every scaffold now ships .claude-plugin/plugin.json, removing the previous asymmetry where only the minimal template was usable with claude -p --plugin-dir. Source: community release notes for [email protected].
• Known issue (#73): packages/create-agent-harness/dist/bin.js discards main()'s return code, so every metaharness subcommand exits 0 regardless of failure. This affects CI scripts that rely on non-zero exit to detect template-generation errors, but it is a CLI bug rather than a defect in the template/host pipeline itself. Source: GitHub issue #73.

Related Pages

Related topics: System Architecture & Kernel, Templates, Hosts & Plugin Manifests

Self-Evolution, Routing & Cost-Pareto

The metaharness project ships three tightly coupled subsystems that together drive an agent harness toward better quality at lower cost over time: a self-evolution engine (in packages/darwin-mode) that mutates and re-evaluates prompt/config candidates, a learned router (in packages/router) that picks the cheapest viable strategy per query, and a Cost-Pareto scorer that keeps the candidate set Pareto-optimal across quality and cost axes.

1. Self-Evolution Engine (GEPA Loop)

The heart of self-evolution lives in the GEPA (Generate-Evaluate-Pareto-Adapt) loop implemented under packages/darwin-mode/src/gepa/loop.ts. Each iteration:

1. Generates a candidate variation of the current harness (prompt edits, tool-config tweaks, or agent-graph rewrites) using mutation operators defined in evolve.ts.
2. Evaluates the candidate by running a deterministic eval suite, producing per-task scores.
3. Pareto-adapts the survivor set by adding the candidate only if it is non-dominated.
4. Emits an updated Pareto archive plus telemetry for downstream training.

The evolve.ts module exposes Evolver, an interface that wraps a base harness, a Scorer, and a Pareto archive; it persists intermediate state so a process crash mid-loop does not corrupt the archive. The candidate emission contract is Candidate = { id, patch, meta } and every candidate is hash-keyed so duplicates are deduplicated cheaply. Source: packages/darwin-mode/src/evolve.ts:1-120.

The scorer.ts module is responsible for normalizing raw eval outputs into a (quality, cost, latency) vector per task. Scoring is pluggable — scorers can be deterministic (regex/assertion-based) or LLM-graded — and the module enforces that every candidate receives the *same* task set in the *same* order, which is a precondition for fair Pareto comparison. Source: packages/darwin-mode/src/scorer.ts:1-90.

2. Cost-Pareto Front

The Pareto front is computed in packages/darwin-mode/src/pareto.ts. Given a list of scored candidates, the algorithm produces a list of non-dominated points where no other candidate is strictly better on both axes (quality↑, cost↓). The module exposes paretoFront(candidates) and dominates(a, b) primitives; both are pure functions that can be unit-tested without an LLM.

Key implementation details:

• Multi-objective dominance: quality dominates cost at user-specified weights, but the default treats them as independent objectives, producing a true front rather than a single optimum.
• Archive mutation: when a new candidate is added, dominated archive entries are pruned; this bounds archive size and ensures each generation's survivors are strictly non-dominated.
• Serialization: the front is persisted as JSON with a schema version field, enabling forward-compatible loading across metaharness versions (relevant to the v0.1.3 release notes, where every scaffold now ships .claude-plugin/plugin.json and uses the same archive loader). Source: packages/darwin-mode/src/pareto.ts:1-150.

The Pareto front is the bridge between the GEPA loop and the router: the router trains on it, not on raw candidates.

3. Router: Picking the Cheapest Viable Strategy

packages/router/src/index.ts implements the runtime router used by every scaffolded harness. The router accepts a query and returns the best (strategy, expectedCost, expectedQuality) triple, where a "strategy" is a concrete harness configuration from the Pareto archive.

The router is a small, fast classifier (typically a logistic-regression or shallow gradient-boosted model) trained over the features extracted from the query. At inference time it:

1. Extracts lightweight features (token-length bucket, intent tag, presence of code blocks, detected language, etc.).
2. Scores each candidate strategy against those features.
3. Returns the strategy whose expected quality exceeds the query's qualityFloor at the lowest expected cost; ties are broken by latency.

Because the router is trained on the *Pareto-optimal* subset rather than the full candidate set, the search space at inference is bounded and the router can run on every query with negligible overhead. Source: packages/router/src/index.ts:1-200.

4. Training the Router

packages/router/src/train.ts consumes the JSON artifacts emitted by the GEPA loop and fits the router model. The training pipeline is offline and reproducible:

Training is invoked by the metaharness train-router CLI command; the resulting artifact is checked into the scaffold so the runtime needs no network access. Source: packages/router/src/train.ts:1-180.

End-to-End Flow

The three subsystems compose into a single feedback loop: GEPA produces a Pareto archive → the trainer consumes the archive → the runtime router uses the trained artifact on live queries → logged traces feed back into the next GEPA generation.

flowchart LR
  A[GEPA Loop] -->|archive.json| B(Pareto Front)
  B --> C[Router Trainer]
  C -->|router.json| D[Runtime Router]
  D -->|query + trace| E[Agent Harness]
  E -->|eval results| A

This closed loop is what makes a metaharness *self-evolving*: every scaffold produced by @ruvnet/agent-harness-generator includes both the GEPA driver and the router, so a fresh metaharness init is already wired for continuous improvement once eval data accumulates. Source: packages/darwin-mode/src/gepa/loop.ts:1-160, packages/darwin-mode/src/pareto.ts:1-150, packages/router/src/index.ts:1-200, packages/router/src/train.ts:1-180, packages/darwin-mode/src/scorer.ts:1-90, packages/darwin-mode/src/evolve.ts:1-120.

Note: the GEPA/router pipeline is independent of the CLI exit-code bug tracked in issue #73; the latter affects only packages/create-agent-harness/dist/bin.js and does not corrupt archive or router artifacts.

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/4

2. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/47

3. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/22

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/48

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/15

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/20

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/ruvnet/metaharness

8. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/ruvnet/metaharness

9. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/73

10. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/ruvnet/metaharness

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/ruvnet/metaharness

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/ruvnet/metaharness

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using metaharness with real data or production workflows.

• Beta feedback: quality & improvement report (DRACO claim retraction, fre - github / github_issue
• ADR-175 feedback: Conformant mode has a structural verification gap (Goo - github / github_issue
• kernel npm package ships no wasm/native artifacts — backend always falls - github / github_issue
• No way to select kernel backend; requested backend silently falls back t - github / github_issue
• harness/metaharness CLIs share subcommand names but emit different outpu - github / github_issue
• bug: minimal template CLAUDE.md documents memory search / route comm - github / github_issue
• metaharness CLI bin.js discards main()'s exit code — all commands exit 0 - github / github_issue
• v0.1.3 — Every scaffold ships .claude-plugin/plugin.json - github / github_release
• Configuration risk requires verification - GitHub / issue