https://github.com/madebywild/agent-harness
Unified AI agent configuration management for Codex, Claude, and Copilot by wild
https://github.com/madebywild/agent-harness
ai ai-agent ai-agents harness harness-engineering harness-framework
Last synced: 3 months ago
JSON representation
Unified AI agent configuration management for Codex, Claude, and Copilot by wild
- Host: GitHub
- URL: https://github.com/madebywild/agent-harness
- Owner: madebywild
- License: mit
- Created: 2026-02-06T19:46:37.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T17:14:11.000Z (3 months ago)
- Last Synced: 2026-04-03T05:12:07.581Z (3 months ago)
- Topics: ai, ai-agent, ai-agents, harness, harness-engineering, harness-framework
- Language: TypeScript
- Homepage: https://wild.as
- Size: 957 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Agent Harness
[](https://nodejs.org/)
[](https://pnpm.io/)
[](LICENSE)
[](https://deepwiki.com/madebywild/agent-harness)
Unified AI agent configuration management for Codex, Claude, Copilot, and Cursor. The Shadcn for agent harnesses.
Agent 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.
Like [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.
## Features
### Unified agent config
- Single source of truth for all agent configurations in the `.harness/` directory
- Multi-provider support with simultaneous output generation for Codex, Claude, Copilot, and Cursor
- System prompt management with provider-specific overrides
- Reusable skill management synchronized across providers
- Third-party skill discovery and import via [skills.sh](https://skills.sh) with audit gating
- Centralized MCP server configuration with merged outputs
- Subagent management with provider-specific rendering
- Lifecycle hook management (webhooks, scripts, notifications)
- Environment variable substitution via `{{PLACEHOLDER}}` syntax with `.env` file support
- Watch mode for automatic regeneration on file changes
- Strict file ownership with manifest-based integrity enforcement
- Explicit schema version management with `doctor` + `migrate`
### Shareable registries (the Shadcn model)
- Pull entities from external git registries directly into your project as full, editable source code
- No hidden abstractions — every pulled file lands in `.harness/src/` where you can inspect, modify, and commit it
- Per-entity registry provenance tracks where each entity originated
- Explicit `registry pull` workflow for refreshing imported entities on your terms
- Preset-based workspace bootstrapping with bundled, local, and registry-backed presets
- Teams can maintain a shared registry of battle-tested prompts, skills, hooks, and MCP configs that any project can adopt
## Quick Start
```bash
npm install --save-dev @madebywild/agent-harness-framework
npx harness init
```
Or start from a bundled preset:
```bash
npx harness init --preset starter
```
For first-run onboarding, you can ask harness to launch a specific agent CLI to author the shared prompt:
```bash
npx harness init --delegate claude
npx harness init --delegate codex
npx harness init --delegate copilot
```
This 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.
### Migrating from existing provider configs (U-Haul)
Already have `CLAUDE.md`, `AGENTS.md`, `.mcp.json`, or other provider-specific files? U-Haul imports them into canonical `.harness/src/` entities in one step:
```bash
npx harness init --u-haul
npx harness init --u-haul --u-haul-precedence codex # override default precedence
```
U-Haul detects legacy assets across all three providers, resolves conflicts via provider precedence (default: `claude > codex > 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.
Then configure your workspace:
```bash
# Launch interactive TUI (default when TTY)
npx harness
# Enable providers
npx harness provider enable codex
npx harness provider enable claude
npx harness provider enable copilot
# Configure a git registry and set it as default
npx harness registry add corp --gitUrl git@github.com:acme/harness-registry.git --ref main
npx harness registry default set corp
# Add a system prompt
npx harness add prompt
# Add a skill
npx harness add skill my-skill
# Find third-party skills via skills.sh
npx harness skill find "code review"
# Import a third-party skill
npx harness skill import owner/repo --skill my-skill
# Add MCP config
npx harness add mcp my-mcp
# Add subagent
npx harness add subagent researcher
# Add lifecycle hook
npx harness add hook my-hook
# List available presets
npx harness preset list
# Describe a preset
npx harness preset describe starter
# Apply a preset after init
npx harness preset apply starter
# Generate outputs
npx harness apply
# Watch for changes
npx harness watch
```
## Installation from source
For development of the library itself:
```bash
git clone
cd agent-harness
pnpm install
pnpm build
```
The CLI is available at `packages/toolkit/dist/cli.js`.
## CLI Commands
| Command | Description |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `npx harness init [--force] [--preset ] [--delegate ]` | Initialize `.harness/` structure, optionally apply a preset, and optionally launch delegated prompt authoring |
| `npx harness init --u-haul [--u-haul-precedence ]` | Import legacy provider configs into `.harness/`, resolve conflicts, and run apply |
| `npx harness` | Interactive TUI on TTY, `plan` on non-TTY/CI |
| `npx harness --interactive` | Force interactive mode |
| `npx harness --version` | Print CLI version |
| `npx harness doctor` | Report schema version health and migration blockers |
| `npx harness migrate [--dryRun]` | Upgrade schema files to latest supported version |
| `npx harness provider enable ` | Enable a provider (codex/claude/copilot/cursor) |
| `npx harness provider disable ` | Disable a provider |
| `npx harness registry list` | List configured registries |
| `npx harness registry add --gitUrl [--ref ]` | Add a Git registry entry |
| `npx harness registry remove ` | Remove a configured registry |
| `npx harness registry default show/set ` | Show or set default registry |
| `npx harness registry pull [ ] [--registry ] [--force]` | Refresh imported entities |
| `npx harness registry validate [--path ]` | Validate a registry's structure |
| `npx harness preset list [--registry ]` | List bundled, local, or registry presets |
| `npx harness preset describe [--registry ]` | Describe a preset |
| `npx harness preset apply [--registry ]` | Materialize a preset into normal harness state |
| `npx harness add prompt [--registry ]` | Add system prompt entity |
| `npx harness skill find ` | Search third-party skills via skills.sh |
| `npx harness skill import --skill [--as ] [--replace]`| Import a third-party skill with audit gating |
| `npx harness add skill [--registry ]` | Add a skill entity |
| `npx harness add mcp [--registry ]` | Add an MCP config entity |
| `npx harness add subagent [--registry ]` | Add a subagent entity |
| `npx harness add hook [--registry ]` | Add a lifecycle hook entity |
| `npx harness remove [--no-delete-source]` | Remove an entity (deletes source by default) |
| `npx harness validate` | Validate manifest and files |
| `npx harness plan` | Preview changes (dry-run) |
| `npx harness apply` | Generate provider outputs |
| `npx harness watch [--debounceMs]` | Watch mode with auto-apply |
Global flags:
- `--cwd `: run against a specific workspace root.
- `--json`: emit a stable machine-readable envelope (`schemaVersion: "1"`).
- `--interactive`: force interactive mode when available.
- `--no-interactive`: force command mode.
## Schema Version Policy
- Normal runtime commands (`plan`, `apply`, `validate`, `watch`, `add/remove`, `provider enable/disable`) require current schema versions.
- If any schema is outdated, run:
1. `npx harness doctor`
2. `npx harness migrate`
3. `npx harness apply`
- If a workspace schema is newer than the installed CLI, commands fail safely with `*_VERSION_NEWER_THAN_CLI`; upgrade the CLI before proceeding.
- `npx harness migrate` creates a backup snapshot under `.harness/.backup//` and writes files atomically.
## Project Structure
```
.harness/
├── manifest.json # Entity + registry config
├── manifest.lock.json # Generated state lock + registry provenance
├── managed-index.json # Managed file index
├── .env # Per-workspace secrets (gitignored)
├── presets/ # Optional local preset packages
└── src/
├── prompts/
│ └── system.md # System prompt
│ ├── system.overrides.codex.yaml
│ ├── system.overrides.claude.yaml
│ └── system.overrides.copilot.yaml
├── skills/
│ └── my-skill/
│ ├── SKILL.md
│ ├── OVERRIDES.codex.yaml
│ ├── OVERRIDES.claude.yaml
│ └── OVERRIDES.copilot.yaml
├── mcp/
├── my-mcp.json
├── my-mcp.overrides.codex.yaml
├── my-mcp.overrides.claude.yaml
└── my-mcp.overrides.copilot.yaml
├── subagents/
│ ├── researcher.md
│ ├── researcher.overrides.codex.yaml
│ ├── researcher.overrides.claude.yaml
│ └── researcher.overrides.copilot.yaml
├── commands/
│ └── fix-issue.md
└── hooks/
└── my-hook.json
.env.harness # Shared env parameters (optionally committed)
```
## Presets
Presets are bootstrap macros, not manifest entities.
- Bundled presets ship with the toolkit package.
- Local presets live under `.harness/presets//`.
- Registry presets live under `presets//` in a git registry.
The bundled `delegate` preset seeds one shared bootstrap prompt for Claude, Codex, Copilot, and Cursor and enables all providers. `init --delegate ` uses that preset and then launches the selected agent CLI to replace the bootstrap content with the real project-specific prompt.
Applying 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.
## Generated Outputs
| Entity | Codex | Claude | Copilot | Cursor |
| --------- | ---------------------------------------- | ------------------------ | --------------------------------- | -------------------------- |
| Prompt | `AGENTS.md` | `.claude/CLAUDE.md` | `.github/copilot-instructions.md` | — |
| Skills | `.codex/skills/` | `.claude/skills/` | `.github/skills/` | `.cursor/skills/` |
| MCP | `.codex/config.toml` | `.mcp.json` | `.vscode/mcp.json` | `.cursor/mcp.json` |
| Subagents | `.codex/config.toml` (merged `agents.*`) | `.claude/agents/.md` | `.github/agents/.agent.md` | `.cursor/agents/.md` |
| Hooks | `.codex/config.toml` | `.claude/settings.json` | `.github/hooks/...` | `.cursor/hooks.json` |
## Monorepo Packages
### `@madebywild/agent-harness-manifest`
Zod schemas and TypeScript types for manifests, locks, and sidecars.
```typescript
import type {
AgentsManifest,
ProviderId,
EntityRef,
} from "@madebywild/agent-harness-manifest";
```
### `@madebywild/agent-harness-framework`
The main toolkit with CLI and core engine.
```typescript
import { Planner, ProviderAdapter } from "@madebywild/agent-harness-framework";
```
## Development
```bash
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run type checks
pnpm typecheck
# Run tests
pnpm test
# Run containerized registry end-to-end tests
pnpm test:e2e:containers
# Lint and format
pnpm check:write
# Watch mode during development
pnpm --filter @madebywild/agent-harness-framework watch
```
## Release
This repository publishes two npm packages in lockstep:
- `@madebywild/agent-harness-manifest`
- `@madebywild/agent-harness-framework`
To release:
1. Bump `version` in both `packages/manifest-schema/package.json` and `packages/toolkit/package.json` to the same semver.
2. Merge the version bump PR.
3. Create and push a `vX.Y.Z` tag (e.g. `v0.2.0`). CI publishes manifest-schema first, then framework.
## Containerized E2E Tests
- `pnpm test` remains fast and does not require Docker.
- `pnpm test:e2e:containers` runs Docker-backed CLI end-to-end tests for remote git registries.
- A Docker-compatible container runtime is required for `pnpm test:e2e:containers`.
- The first run may be slower because it can pull the Gitea container image.
## Architecture
See [docs/architecture.md](docs/architecture.md) for detailed design documentation.
## Supported Providers
- **OpenAI Codex** - AGENTS.md and .codex/ configuration
- **Anthropic Claude Code** - CLAUDE.md and .claude/ configuration
- **GitHub Copilot** - .github/ copilot-instructions and skills
- **Cursor** - .cursor/ skills, agents, MCP, and hooks
## License
MIT