metaharness

Scaffold your own focused AI agent harness — like ruflo, uniquely yours.

Proven at the cost-Pareto frontier. Same "evolve the harness" thesis, measured: the Darwin harness resolves real SWE-bench Lite issues at 34.0% single-trajectory (~$0.005/inst) and 39.7% Best-of-3 (~$0.015/inst) — conformant, official harness. Live Cost–Performance leaderboard · @metaharness/darwin.

Published as metaharness (the metaharness and harness CLIs). Earlier versions were published as create-agent-harness.

Quick start

npx metaharness my-bot

You'll be prompted for template, host, description. Out comes a complete npm package ready to npm publish.

Non-interactive

npx metaharness my-legal-bot \
  --template vertical:legal \
  --host claude-code \
  --description "Contract redline + risk rating"

Templates

| Template | Best for | |---|---| | minimal | Custom starter — kernel only | | vertical:devops | Incident response, on-call workflows | | vertical:support | Customer support, KB-RAG, escalation | | vertical:trading | Quant trading (paper-default, circuit breakers) | | vertical:legal | Contract review with citation checking | | vertical:research | Multi-source dossier with evidence grading |

Hosts

--host selects which host adapter ships with your harness:

| Host | What you get | |---|---| | claude-code | .claude/settings.json with MCP + hooks | | codex | ~/.codex/config.toml with [mcp_servers.*] | | pi-dev | Pi extension (TypeScript, no MCP by design) | | hermes | cli-config.yaml + optional-mcps/*.yaml | | openclaw | ~/.openclaw/openclaw.json + workspace SKILL.md + install runbook | | rvm | RVM partition manifest + capability table + wasm-guest + install runbook (hardware-isolated) |

Multi-host: pass --host multiple times.

Also ships the harness CLI

harness sign      # produce/update the witness manifest
harness verify    # check signature
harness doctor    # smoke-check a scaffolded harness
harness score     # runtime-readiness badges for a local repo
harness help

harness score vs metaharness score — two different scorecards (#15)

The two CLIs both accept score but emit different, purpose-specific JSON — so check the schema discriminator before parsing:

| Command | Purpose | JSON discriminator | |---|---|---| | harness score <dir> --json | Runtime-readiness badges (score + mcpRisk / releaseReady / testsDetected / sbom / witnessSigned) | "schema": "harness-quickcheck-v1" (string) | | metaharness score <dir> --json | 5-dimension harness-fit scorecard (harnessFit / compileConfidence / …) | "schema": 1 (number) |

They are not interchangeable. A consumer wiring one into a pipeline expecting the other should branch on schema (typeof out.schema === 'string' ⇒ harness badges; === 1 ⇒ metaharness scorecard) and refuse the wrong shape rather than silently defaulting missing fields to 0.

Optional Cognitum Meta-Proxy sidecar

Meta-Proxy is an optional local Rust sidecar, not an npm dependency and not part of normal harness scaffolding. Install it only when you want a locally bound, Claude-compatible routing endpoint with Meta-Proxy's own Cognitum OAuth flow:

npx metaharness proxy install --yes   # signed v0.7.1 download; checksum + Ed25519 verified
npx metaharness proxy run -- claude   # starts the sidecar and routes this Claude session through it
npx metaharness proxy run --policy critical -- claude -p "review this migration"

proxy run is the activation path: it supplies ANTHROPIC_BASE_URL and the local proxy bearer token only to the child process. It does not modify global Claude settings, project files, or persisted client configuration. With the Meta-Proxy automatic-failover release installed, ordinary requests use the user's Claude Passthrough identity; trusted rate-limit telemetry can then select consented Cloud or Sponsored capacity per request. Cognitum login is needed only for Cloud routing, not for installation or normal Passthrough.

Use npx metaharness proxy login to authorize Cognitum Cloud routing, and npx metaharness proxy status to inspect the managed sidecar.

Per-worktree routing policy

proxy run attaches a short-lived, HMAC-signed local capability to the launched process. The policy is scoped to a one-way fingerprint of the current worktree; neither its path nor repository metadata leaves the machine.

• critical — suppress automatic Power Saver and Sponsored failover for this worktree. Explicit manual controls still apply.
• standard — the normal automatic policy: Power Saver at 80% utilization, Sponsored only after exhaustion and only with consent.
• economy — Power Saver may start at 60% utilization; it retains all consent gates and the Sponsored-at-exhaustion limit.

The capability is verified by Meta-Proxy, not inferred from .claude, a Git branch name, or any repository-controlled file. Meta-Proxy v0.4.0 or later is required for per-worktree policies; older releases reject the scoped token.

proxy install downloads the platform archive from the public meta-proxy-dist release channel only after explicit --yes consent. The CLI verifies the signed SHA256SUMS manifest against a public key pinned in MetaHarness before it extracts or replaces a binary. The sidecar is installed under ~/.metaharness/meta-proxy/; credentials remain in Meta-Proxy's own storage.

Other commands: proxy stop, proxy path, and proxy logout.

Eject from ruflo

If you've been using ruflo and want your own focused harness from it:

npx metaharness --from-existing ./

Lifts agents/skills/commands, rewrites every ruflo / claude-flow reference, preserves attribution blocks marked with <!-- ruflo-attribution-block -->.

Full walkthrough

See USAGE.md.

License

MIT