{"id":48489584,"url":"https://github.com/madebywild/agent-harness","last_synced_at":"2026-04-07T11:04:32.248Z","repository":{"id":345821728,"uuid":"1151703052","full_name":"madebywild/agent-harness","owner":"madebywild","description":"Unified AI agent configuration management for Codex, Claude, and Copilot by wild","archived":false,"fork":false,"pushed_at":"2026-04-02T17:14:11.000Z","size":980,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T05:12:07.581Z","etag":null,"topics":["ai","ai-agent","ai-agents","harness","harness-engineering","harness-framework"],"latest_commit_sha":null,"homepage":"https://wild.as","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madebywild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-06T19:46:37.000Z","updated_at":"2026-04-02T17:14:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/madebywild/agent-harness","commit_stats":null,"previous_names":["madebywild/agent-harness"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/madebywild/agent-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebywild%2Fagent-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebywild%2Fagent-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebywild%2Fagent-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebywild%2Fagent-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madebywild","download_url":"https://codeload.github.com/madebywild/agent-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madebywild%2Fagent-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31509946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-agents","harness","harness-engineering","harness-framework"],"created_at":"2026-04-07T11:04:29.177Z","updated_at":"2026-04-07T11:04:32.239Z","avatar_url":"https://github.com/madebywild.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Harness\n\n![Cover](public/cover.webp)\n\n[![Node Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)\n[![Package Manager](https://img.shields.io/badge/pnpm-10.2.0-blue)](https://pnpm.io/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/madebywild/agent-harness)\n\nUnified AI agent configuration management for Codex, Claude, Copilot, and Cursor. The Shadcn for agent harnesses.\n\nAgent Harness is a TypeScript CLI tool and library that manages AI agent configurations (prompts, skills, MCP server configs, and subagents) from a single source of truth, generating provider-specific outputs for OpenAI Codex, Anthropic Claude Code, GitHub Copilot, and Cursor.\n\nLike [shadcn/ui](https://ui.shadcn.com/) does for UI components, Agent Harness gives you full ownership of your agent configuration. Pull shared entities from external git registries into your project as full source code — not as opaque library imports. You can inspect, modify, and version every file. The CLI manages the plumbing; you own the content.\n\n## Features\n\n### Unified agent config\n\n- Single source of truth for all agent configurations in the `.harness/` directory\n- Multi-provider support with simultaneous output generation for Codex, Claude, Copilot, and Cursor\n- System prompt management with provider-specific overrides\n- Reusable skill management synchronized across providers\n- Third-party skill discovery and import via [skills.sh](https://skills.sh) with audit gating\n- Centralized MCP server configuration with merged outputs\n- Subagent management with provider-specific rendering\n- Lifecycle hook management (webhooks, scripts, notifications)\n- Environment variable substitution via `{{PLACEHOLDER}}` syntax with `.env` file support\n- Watch mode for automatic regeneration on file changes\n- Strict file ownership with manifest-based integrity enforcement\n- Explicit schema version management with `doctor` + `migrate`\n\n### Shareable registries (the Shadcn model)\n\n- Pull entities from external git registries directly into your project as full, editable source code\n- No hidden abstractions — every pulled file lands in `.harness/src/` where you can inspect, modify, and commit it\n- Per-entity registry provenance tracks where each entity originated\n- Explicit `registry pull` workflow for refreshing imported entities on your terms\n- Preset-based workspace bootstrapping with bundled, local, and registry-backed presets\n- Teams can maintain a shared registry of battle-tested prompts, skills, hooks, and MCP configs that any project can adopt\n\n## Quick Start\n\n```bash\nnpm install --save-dev @madebywild/agent-harness-framework\nnpx harness init\n```\n\nOr start from a bundled preset:\n\n```bash\nnpx harness init --preset starter\n```\n\nFor first-run onboarding, you can ask harness to launch a specific agent CLI to author the shared prompt:\n\n```bash\nnpx harness init --delegate claude\nnpx harness init --delegate codex\nnpx harness init --delegate copilot\n```\n\nThis path auto-applies the bundled `delegate` preset, seeds `.harness/src/prompts/system.md` with one shared bootstrap prompt for all providers, and then launches the selected agent CLI so it can inspect the repository and finish setup through non-interactive `pnpm harness` or `npx harness` commands.\n\n### Migrating from existing provider configs (U-Haul)\n\nAlready have `CLAUDE.md`, `AGENTS.md`, `.mcp.json`, or other provider-specific files? U-Haul imports them into canonical `.harness/src/` entities in one step:\n\n```bash\nnpx harness init --u-haul\nnpx harness init --u-haul --u-haul-precedence codex  # override default precedence\n```\n\nU-Haul detects legacy assets across all three providers, resolves conflicts via provider precedence (default: `claude \u003e codex \u003e copilot`), materializes canonical entities, auto-enables contributing providers, removes imported legacy files, and runs `apply`. See [docs/toolkit.u-haul.md](docs/toolkit.u-haul.md) for the full behavior specification.\n\nThen configure your workspace:\n\n```bash\n# Launch interactive TUI (default when TTY)\nnpx harness\n\n# Enable providers\nnpx harness provider enable codex\nnpx harness provider enable claude\nnpx harness provider enable copilot\n\n# Configure a git registry and set it as default\nnpx harness registry add corp --gitUrl git@github.com:acme/harness-registry.git --ref main\nnpx harness registry default set corp\n\n# Add a system prompt\nnpx harness add prompt\n\n# Add a skill\nnpx harness add skill my-skill\n\n# Find third-party skills via skills.sh\nnpx harness skill find \"code review\"\n\n# Import a third-party skill\nnpx harness skill import owner/repo --skill my-skill\n\n# Add MCP config\nnpx harness add mcp my-mcp\n\n# Add subagent\nnpx harness add subagent researcher\n\n# Add lifecycle hook\nnpx harness add hook my-hook\n\n# List available presets\nnpx harness preset list\n\n# Describe a preset\nnpx harness preset describe starter\n\n# Apply a preset after init\nnpx harness preset apply starter\n\n# Generate outputs\nnpx harness apply\n\n# Watch for changes\nnpx harness watch\n```\n\n## Installation from source\n\nFor development of the library itself:\n\n```bash\ngit clone \u003crepo-url\u003e\ncd agent-harness\npnpm install\npnpm build\n```\n\nThe CLI is available at `packages/toolkit/dist/cli.js`.\n\n## CLI Commands\n\n| Command                                                                 | Description                                                                                                   |\n| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `npx harness init [--force] [--preset \u003cid\u003e] [--delegate \u003cprovider\u003e]`    | Initialize `.harness/` structure, optionally apply a preset, and optionally launch delegated prompt authoring |\n| `npx harness init --u-haul [--u-haul-precedence \u003cprovider\u003e]`            | Import legacy provider configs into `.harness/`, resolve conflicts, and run apply                            |\n| `npx harness`                                                           | Interactive TUI on TTY, `plan` on non-TTY/CI                                                                  |\n| `npx harness --interactive`                                             | Force interactive mode                                                                                        |\n| `npx harness --version`                                                 | Print CLI version                                                                                             |\n| `npx harness doctor`                                                    | Report schema version health and migration blockers                                                           |\n| `npx harness migrate [--dryRun]`                                        | Upgrade schema files to latest supported version                                                              |\n| `npx harness provider enable \u003cid\u003e`                                      | Enable a provider (codex/claude/copilot/cursor)                                                               |\n| `npx harness provider disable \u003cid\u003e`                                     | Disable a provider                                                                                            |\n| `npx harness registry list`                                             | List configured registries                                                                                    |\n| `npx harness registry add \u003cname\u003e --gitUrl \u003curl\u003e [--ref \u003cbranch\u003e]`       | Add a Git registry entry                                                                                      |\n| `npx harness registry remove \u003cname\u003e`                                    | Remove a configured registry                                                                                  |\n| `npx harness registry default show/set \u003cname\u003e`                          | Show or set default registry                                                                                  |\n| `npx harness registry pull [\u003ctype\u003e \u003cid\u003e] [--registry \u003cname\u003e] [--force]` | Refresh imported entities                                                                                     |\n| `npx harness registry validate [--path \u003cpath\u003e]`                         | Validate a registry's structure                                                                               |\n| `npx harness preset list [--registry \u003cname\u003e]`                           | List bundled, local, or registry presets                                                                      |\n| `npx harness preset describe \u003cid\u003e [--registry \u003cname\u003e]`                  | Describe a preset                                                                                             |\n| `npx harness preset apply \u003cid\u003e [--registry \u003cname\u003e]`                     | Materialize a preset into normal harness state                                                                |\n| `npx harness add prompt [--registry \u003cname\u003e]`                            | Add system prompt entity                                                                                      |\n| `npx harness skill find \u003cquery\u003e`                                        | Search third-party skills via skills.sh                                                                       |\n| `npx harness skill import \u003csource\u003e --skill \u003cid\u003e [--as \u003cid\u003e] [--replace]`| Import a third-party skill with audit gating                                                                  |\n| `npx harness add skill \u003cid\u003e [--registry \u003cname\u003e]`                        | Add a skill entity                                                                                            |\n| `npx harness add mcp \u003cid\u003e [--registry \u003cname\u003e]`                          | Add an MCP config entity                                                                                      |\n| `npx harness add subagent \u003cid\u003e [--registry \u003cname\u003e]`                     | Add a subagent entity                                                                                         |\n| `npx harness add hook \u003cid\u003e [--registry \u003cname\u003e]`                         | Add a lifecycle hook entity                                                                                   |\n| `npx harness remove \u003ctype\u003e \u003cid\u003e [--no-delete-source]`                   | Remove an entity (deletes source by default)                                                                  |\n| `npx harness validate`                                                  | Validate manifest and files                                                                                   |\n| `npx harness plan`                                                      | Preview changes (dry-run)                                                                                     |\n| `npx harness apply`                                                     | Generate provider outputs                                                                                     |\n| `npx harness watch [--debounceMs]`                                      | Watch mode with auto-apply                                                                                    |\n\nGlobal flags:\n\n- `--cwd \u003cpath\u003e`: run against a specific workspace root.\n- `--json`: emit a stable machine-readable envelope (`schemaVersion: \"1\"`).\n- `--interactive`: force interactive mode when available.\n- `--no-interactive`: force command mode.\n\n## Schema Version Policy\n\n- Normal runtime commands (`plan`, `apply`, `validate`, `watch`, `add/remove`, `provider enable/disable`) require current schema versions.\n- If any schema is outdated, run:\n  1. `npx harness doctor`\n  2. `npx harness migrate`\n  3. `npx harness apply`\n- If a workspace schema is newer than the installed CLI, commands fail safely with `*_VERSION_NEWER_THAN_CLI`; upgrade the CLI before proceeding.\n- `npx harness migrate` creates a backup snapshot under `.harness/.backup/\u003ctimestamp\u003e/` and writes files atomically.\n\n## Project Structure\n\n```\n.harness/\n├── manifest.json          # Entity + registry config\n├── manifest.lock.json     # Generated state lock + registry provenance\n├── managed-index.json     # Managed file index\n├── .env                   # Per-workspace secrets (gitignored)\n├── presets/               # Optional local preset packages\n└── src/\n    ├── prompts/\n    │   └── system.md                    # System prompt\n    │   ├── system.overrides.codex.yaml\n    │   ├── system.overrides.claude.yaml\n    │   └── system.overrides.copilot.yaml\n    ├── skills/\n    │   └── my-skill/\n    │       ├── SKILL.md\n    │       ├── OVERRIDES.codex.yaml\n    │       ├── OVERRIDES.claude.yaml\n    │       └── OVERRIDES.copilot.yaml\n    ├── mcp/\n        ├── my-mcp.json\n        ├── my-mcp.overrides.codex.yaml\n        ├── my-mcp.overrides.claude.yaml\n        └── my-mcp.overrides.copilot.yaml\n    ├── subagents/\n    │   ├── researcher.md\n    │   ├── researcher.overrides.codex.yaml\n    │   ├── researcher.overrides.claude.yaml\n    │   └── researcher.overrides.copilot.yaml\n   ├── commands/\n   │   └── fix-issue.md\n    └── hooks/\n        └── my-hook.json\n.env.harness                   # Shared env parameters (optionally committed)\n```\n\n## Presets\n\nPresets are bootstrap macros, not manifest entities.\n\n- Bundled presets ship with the toolkit package.\n- Local presets live under `.harness/presets/\u003cid\u003e/`.\n- Registry presets live under `presets/\u003cid\u003e/` in a git registry.\n\nThe bundled `delegate` preset seeds one shared bootstrap prompt for Claude, Codex, Copilot, and Cursor and enables all providers. `init --delegate \u003cprovider\u003e` uses that preset and then launches the selected agent CLI to replace the bootstrap content with the real project-specific prompt.\n\nApplying a preset materializes normal harness state such as enabled providers, prompt/skill/subagent sources, settings, and commands. After that, the usual `validate`, `plan`, and `apply` workflow remains unchanged.\n\n## Generated Outputs\n\n| Entity    | Codex                                    | Claude                   | Copilot                           | Cursor                     |\n| --------- | ---------------------------------------- | ------------------------ | --------------------------------- | -------------------------- |\n| Prompt    | `AGENTS.md`                              | `.claude/CLAUDE.md`      | `.github/copilot-instructions.md` | —                          |\n| Skills    | `.codex/skills/`                         | `.claude/skills/`        | `.github/skills/`                 | `.cursor/skills/`          |\n| MCP       | `.codex/config.toml`                     | `.mcp.json`              | `.vscode/mcp.json`                | `.cursor/mcp.json`         |\n| Subagents | `.codex/config.toml` (merged `agents.*`) | `.claude/agents/\u003cid\u003e.md` | `.github/agents/\u003cid\u003e.agent.md`    | `.cursor/agents/\u003cid\u003e.md`   |\n| Hooks     | `.codex/config.toml`                     | `.claude/settings.json`  | `.github/hooks/...`               | `.cursor/hooks.json`       |\n\n## Monorepo Packages\n\n### `@madebywild/agent-harness-manifest`\n\nZod schemas and TypeScript types for manifests, locks, and sidecars.\n\n```typescript\nimport type {\n  AgentsManifest,\n  ProviderId,\n  EntityRef,\n} from \"@madebywild/agent-harness-manifest\";\n```\n\n### `@madebywild/agent-harness-framework`\n\nThe main toolkit with CLI and core engine.\n\n```typescript\nimport { Planner, ProviderAdapter } from \"@madebywild/agent-harness-framework\";\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run type checks\npnpm typecheck\n\n# Run tests\npnpm test\n\n# Run containerized registry end-to-end tests\npnpm test:e2e:containers\n\n# Lint and format\npnpm check:write\n\n# Watch mode during development\npnpm --filter @madebywild/agent-harness-framework watch\n```\n\n## Release\n\nThis repository publishes two npm packages in lockstep:\n\n- `@madebywild/agent-harness-manifest`\n- `@madebywild/agent-harness-framework`\n\nTo release:\n\n1. Bump `version` in both `packages/manifest-schema/package.json` and `packages/toolkit/package.json` to the same semver.\n2. Merge the version bump PR.\n3. Create and push a `vX.Y.Z` tag (e.g. `v0.2.0`). CI publishes manifest-schema first, then framework.\n\n## Containerized E2E Tests\n\n- `pnpm test` remains fast and does not require Docker.\n- `pnpm test:e2e:containers` runs Docker-backed CLI end-to-end tests for remote git registries.\n- A Docker-compatible container runtime is required for `pnpm test:e2e:containers`.\n- The first run may be slower because it can pull the Gitea container image.\n\n## Architecture\n\nSee [docs/architecture.md](docs/architecture.md) for detailed design documentation.\n\n## Supported Providers\n\n- **OpenAI Codex** - AGENTS.md and .codex/ configuration\n- **Anthropic Claude Code** - CLAUDE.md and .claude/ configuration\n- **GitHub Copilot** - .github/ copilot-instructions and skills\n- **Cursor** - .cursor/ skills, agents, MCP, and hooks\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadebywild%2Fagent-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadebywild%2Fagent-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadebywild%2Fagent-harness/lists"}