Agent Harness

agent-harness

=22" src="https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white" />

Hosts:

Assets:

Discover anywhere. Install everywhere.

agent-harness is a reviewable supply chain for reusable AI-agent assets: discover trusted sources, rank workspace-specific recommendations, mirror pinned bundles, stage local files, activate host views, and wire everything into the agent host you already use. ARD-compatible (v0.9) as both publisher and consumer.

Proof points

• Published CLI: @ar27111994/agent-harness on npm, with release artifacts on GitHub Releases.
• Quality-gated: every release path is backed by the quality workflow.
• Discoverable: listed through GitHub Explore topic visibility as topic metadata, not an endorsement.
• Cross-host today: VS Code/GitHub Copilot, OpenCode, Cursor, Zed, Claude Code, Pi, and OpenAI Codex.

▶️ Watch the demo:

[](https://youtu.be/u1OmcS97iOg)

Sound-on walkthrough: youtu.be/u1OmcS97iOg

• Video source: agent-harness-demo-video, rendered with Remotion and kept outside this package so npm tarballs stay lean.
• Terminal source: docs/demo/workspace-opencode-demo.mjs, which records the public-safe OpenCode quick-start transcript and generated-output tree.
• Walkthrough notes: docs/demo/v2-opencode-walkthrough.md, covering the full v2 before/after flow.

The core model is deliberately boring in the best way: one command surface, a host-adapter boundary, preview-first writes, and explicit native-install steps. The lifecycle stays consistent across hosts while each adapter owns the files, settings, apply/reset behavior, and safety boundaries required by that host.

Table of contents

• [What this project does](#what-this-project-does)
• [Lifecycle model](#lifecycle-model)
• [Supported hosts](#supported-hosts)
• [Where it fits](#where-it-fits)
• [What it produces](#what-it-produces)
• [Quick start](#quick-start)
• [Usage examples](#usage-examples)
• [Key playbooks](#key-playbooks)
• [Command reference](#command-reference)
• [Host wire-in details](#host-wire-in-details)
• [Discovery and recommendations](#discovery-and-recommendations)
• [Environment variables](#environment-variables)
• [Generated and managed files](#generated-and-managed-files)
• [Repository structure](#repository-structure)
• [Development and validation](#development-and-validation)
• [Troubleshooting](#troubleshooting)
• [FAQ](#faq)
• [Security and trust center](#security-and-trust-center)
• [Current boundaries](#current-boundaries)
• [Related documentation](#related-documentation)
• [Sponsor](#sponsor)
• [License](#license)

Key Playbooks

• Agent setup playbook
• Discovery breadth playbook
• Demand detection playbook
• Demand detection coverage
• Source coverage playbook
• Catalog breadth guide
• Semantic scoring guide
• AI enrichment playbook
• Asset update playbook
• Logging strategy
• Troubleshooting guide
• Recommendation policy playbook
• Workspace evolution control-loop playbook
• End-user harness maintenance guide
• Security and trust center
• v2 safe defaults
• v2 CLI and report contract
• v1 to v2 upgrade guide
• Scheduled maintenance workflow
• Release process

What this project does

agent-harness automates the lifecycle of reusable agent assets:

1. Scans a target workspace to infer demand signals.
2. Loads configured and generated discovery sources.
3. Harvests candidate agent assets from local sources, source packs, documentation sources, package registries, and marketplace references.
4. Recomputes ranked recommendations from selected catalog entries.
5. Mirrors the bounded selected asset set into reproducible local artifacts.
6. Stages mirrored bundle assets into lifecycle-host package stores.
7. Executes explicit host-native install/verify/remove operations where an adapter supports them.
8. Activates ranked assets into host runtime views.
9. Wires the activated assets into a target workspace through a selected host adapter.

The goal is to make high-quality reusable agent context portable across tools without hardcoding one workstation, one operating system, or one AI host.

Lifecycle model

The project intentionally separates these stages:

| Stage | Purpose | Typical output | | ----------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | discover | Build demand profiles, source indexes, catalogs, selections, and source-utilization reports. | discover/output/, discover/catalog.assets.jsonl | | recommend | Rank assets per recommendation host using policy, demand signals, trust, cost, diversity, and caps. | state/recommendations.json | | mirror | Build mirror plans, bundle locks, raw artifact caches, quarantine data, and audit records. | mirror/ | | stage | Stage mirrored bundle assets, reconcile generations, and explicitly run supported host-native installs. | install/, state/install/ | | activate | Materialize active runtime views for lifecycle hosts from staged packages and recommendations. | activate/ | | wire | Preview by default, or explicitly apply/reset host-specific workspace integration. | host-specific files plus wire plans | | workspace | Run the end-to-end lifecycle for a selected host and then apply wire-in. | full pipeline output |

stage is the clearer mental model for this phase: the harness stages a bounded mirrored bundle subset into its managed lifecycle store. The CLI still accepts install as an alias because host-native install/verify/remove operations also live in that command group.

Two host concepts are important:

• Lifecycle host: the stage/activation package layout used to materialize assets.
• Recommendation host: the host-specific policy used for ranking and budgets.

Some adapters intentionally reuse another lifecycle host while keeping their own recommendation host. For example, Cursor reuses the Copilot-compatible lifecycle host but ranks through the cursor policy.

wire is intentionally non-mutating unless you pass --apply or --reset; use the default preview mode to inspect target paths and planned writes before changing host files.

Supported hosts

agent-harness currently registers seven host adapters in src/host-adapters/registry.ts.

| CLI target | Aliases | Lifecycle host | Recommendation host | Default bundles | Wire style | | ------------- | --------------------------- | ---------------- | ------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- | | vscode | copilot | copilot-vscode | copilot-vscode | copilot-core, community-stable, shared-mcp | VS Code user settings plus workspace instructions | | opencode | open-code | opencode | opencode | opencode-global, community-stable, shared-mcp | project-local .opencode overlay and managed links | | cursor | - | copilot-vscode | cursor | copilot-core, community-stable, shared-mcp | project-local Cursor rules and managed assets | | zed | - | opencode | zed | opencode-global, community-stable, shared-mcp | project-local .rules, .zed/settings.json, and managed assets | | claude-code | claude, claudecode | opencode | claude-code | opencode-global, community-stable, shared-mcp | project-local Claude context, rules, skills, and commands | | pi | pi-coding-agent | opencode | pi | opencode-global, community-stable | project-local Pi agent/system context, skills, prompts, and settings | | codex | openai-codex, codex-app | opencode | codex | opencode-global, community-stable, shared-mcp | project-local AGENTS.md, .agents skills/plugins, and .codex references |

Use setup hosts to print the registered adapters from the local build:

agent-harness setup hosts

Where it fits

agent-harness is the supply-chain layer that decides what reusable agent assets enter a workspace and how they are staged, activated, reviewed, and wired. It does not run agents. It prepares inspectable inputs for the host or harness you already use.

| Tool or category | What it does | Boundary | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Curated skill/plugin libraries | Help you find and install assets from one ecosystem or curated catalog. | Usually focused on acquisition, not cross-host lifecycle state, pinned mirrors, quarantine, and resettable wire plans. | | MCP/server lists | Help you discover servers and integration ideas. | Lists are references; they do not decide what enters a workspace, stage reproducible artifacts, or manage host-specific wiring. | | Agent runtime harnesses | Run agents, tasks, models, tools, and sessions. | agent-harness is not the runtime. It manages reusable assets before they enter one. | | agent-harness | Discovers sources, ranks recommendations, mirrors pinned bundles, stages/activates assets, quarantines risky inputs, and wires selected assets into supported hosts with preview/apply/reset semantics. | Supply-chain and workspace integration layer for reusable AI-agent assets. |

The practical lifecycle is: discover -> recommend -> mirror -> stage -> activate -> wire. Official and verified sources are preferred over popularity-only signals, official-first-party sources are demoted when owner/publisher evidence fails verification, mirrored generations are pinned for review, risky candidates route through quarantine, and native/global host installs remain explicit instead of hidden inside workspace .

ARD interoperability

Tagline: Discover anywhere. Install everywhere.

agent-harness is both an ARD publisher and an ARD consumer, implementing the Agentic Resource Discovery v0.9 specification (backed by Google, Microsoft, Hugging Face, GitHub, NVIDIA, and others).

Publisher — .well-known/ai-catalog.json

Every discover select or discover full run builds a selected asset catalog. Export it as an ARD-compliant catalog so registries can discover agent-harness-curated assets:

agent-harness discover ard-export
# → .well-known/ai-catalog.json

ARD registries crawl /.well-known/ai-catalog.json at your domain to index agent-harness assets alongside assets from other publishers. The export maps every AssetCatalogEntry to an ARD entry with:

• URN identifier (urn:ai:::) — domain-backed identity
• Media type (application/mcp-server+json, application/ai-skill, etc.) from AssetKind
• Trust manifest — OMS signatures, publisher verification, compliance attestations
• Representative queries — synthetic natural-language queries for semantic discovery

Consumer — ARD registry adapter

agent-harness can consume ARD-compliant registries as discovery sources via POST /search. The registry adapter maps ARD results back to AssetCatalogEntry for the full mirror/stage/activate/wire pipeline. See discover sync and the ard-registry source kind (#327).

Architecture

graph LR
    A[agent-harnessPublisher] -->|ai-catalog.json| B[ARD RegistriesGitHub Agent FinderHuggingFace Discover]
    B -->|POST /search| C[agent-harnessConsumer]
    C -->|mirror → stage → activate → wire| D[Host IDEsVS Code,

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ar27111994](https://github.com/ar27111994)
- **Source:** [ar27111994/agent-harness](https://github.com/ar27111994/agent-harness)
- **License:** MIT
- **Homepage:** https://deepwiki.com/ar27111994/agent-harness

Install and usage instructions live in the source repository linked above.