# Agent Harness > Node.js TypeScript CLI for discovering, staging, activating, and wiring reusable AI-agent assets across VS Code/Copilot, OpenCode, Cursor, Zed, Claude Code, and Pi. - **Type:** MCP server - **Install:** `agentstack add mcp-ar27111994-agent-harness` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ar27111994](https://agentstack.voostack.com/s/ar27111994) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ar27111994](https://github.com/ar27111994) - **Source:** https://github.com/ar27111994/agent-harness - **Website:** https://deepwiki.com/ar27111994/agent-harness ## Install ```sh agentstack add mcp-ar27111994-agent-harness ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://www.npmjs.com/package/@ar27111994/agent-harness), with release artifacts on [GitHub Releases](https://github.com/ar27111994/agent-harness/releases). - **Quality-gated:** every release path is backed by the [quality workflow](https://github.com/ar27111994/agent-harness/actions/workflows/quality.yml). - **Discoverable:** listed through [GitHub Explore topic visibility](https://github.com/github/explore/pull/5175) 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](https://youtu.be/u1OmcS97iOg) - **Video source:** [`agent-harness-demo-video`](https://github.com/ar27111994/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`](https://github.com/ar27111994/agent-harness/blob/main/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`](https://github.com/ar27111994/agent-harness/blob/main/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](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AGENT-SETUP-PLAYBOOK.md) - [Discovery breadth playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md) - [Demand detection playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DEMAND-DETECTION-PLAYBOOK.md) - [Demand detection coverage](https://github.com/ar27111994/agent-harness/blob/main/docs/reference/DEMAND-DETECTION-COVERAGE.md) - [Source coverage playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/SOURCE-COVERAGE-PLAYBOOK.md) - [Catalog breadth guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/CATALOG-BREADTH.md) - [Semantic scoring guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/SEMANTIC-SCORING.md) - [AI enrichment playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AI-ENRICHMENT-PLAYBOOK.md) - [Asset update playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/ASSET-UPDATE-PLAYBOOK.md) - [Logging strategy](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/LOGGING-STRATEGY.md) - [Troubleshooting guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/TROUBLESHOOTING.md) - [Recommendation policy playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/RECOMMENDATION-POLICY-PLAYBOOK.md) - [Workspace evolution control-loop playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/WORKSPACE-EVOLUTION-PLAYBOOK.md) - [End-user harness maintenance guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/HARNESS-MAINTENANCE-GUIDE.md) - [Security and trust center](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/TRUST-CENTER.md) - [v2 safe defaults](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/SAFE-DEFAULTS.md) - [v2 CLI and report contract](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V2-CONTRACT.md) - [v1 to v2 upgrade guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V1-TO-V2-UPGRADE.md) - [Scheduled maintenance workflow](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/MAINTENANCE-WORKFLOW.md) - [Release process](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/RELEASE-PROCESS.md) ## 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: ```bash 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](https://agenticresourcediscovery.org/spec) 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: ```bash 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 ```mermaid 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ar27111994-agent-harness - Seller: https://agentstack.voostack.com/s/ar27111994 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.