An open specification for portable AI coding harnesses.
A vendor-neutral harness.yaml format that captures the complete operational context of an AI coding agent —
plugins, MCP servers, environment, instructions, and permissions.
What MCP is to tool communication, the Harness Protocol is to harness configuration.
AI coding tools — Claude Code, Cursor, GitHub Copilot — each have their own proprietary format for capturing agent context. A configuration tuned for one tool can't be shared with a teammate on another, published for a team to reuse, or carried when you switch tools.
The Harness Protocol defines a common format so harness configurations become portable, shareable artifacts — the same way MCP made tool communication portable.
$schema: https://harnessprotocol.io/schema/v1/harness.schema.json
version: "1"
metadata:
name: data-engineer
description: Harness for data engineering work in Go and SQL.
plugins:
- name: sql-explorer
source: acme-org/sql-explorer
version: "^1.2.0"
mcp-servers:
filesystem:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
permissions:
tools:
allow: [Read, Glob, Grep, Write, Edit]
deny: ["mcp__*__drop_*"]A profile is a YAML file validated against the Harness Protocol JSON Schema, which is the authoritative source for conformance.
The specification is organized into three decoupled layers — a tool can implement Schema-layer validation today with no dependency on the others.
| Layer | What it covers | Status |
|---|---|---|
| Schema | The harness.yaml format, JSON Schema validation, security model, plugin manifest |
🟢 v1 — current |
| Exchange | Harness-to-harness sharing: publish, fetch, and compose across tools and teams | ⚪ v2 — planned |
| Registry | Hosted discovery at harnessprotocol.io: search, publish, version resolution, integrity | ⚪ v2/v3 — planned |
| Repository | What it is | Start here if you want to… |
|---|---|---|
| harness-kit ⭐ | The reference implementation — parser, validator, plugin loader, MCP lifecycle manager, and CLI | Use the protocol today |
| harness-protocol | The specification — JSON Schema, protocol prose, security model, and HEPs | Read or contribute to the spec |
| homebrew-tap | Homebrew tap for harness-kit | brew install the CLI |
Conformance doesn't require harness-kit — any implementation that correctly validates and applies
harness.yamlper the spec is conformant.
🛠️ Harness authors — writing harness.yaml for your project or team:
- Profile schema reference — every field, explained
- Example profiles — annotated configs to copy from
harness-kit— validate and apply your file
⚙️ Tool implementers — building a conformant implementation or IDE integration:
- Overview — what the protocol is and how the layers fit
- Architecture — system model and trust boundaries
- Application pipeline — how a profile becomes effective configuration
- Security model — sensitive data, permissions, and the threat model
Normative spec changes go through the HEP (Harness Enhancement Proposal) process; editorial fixes can be submitted directly as pull requests. See CONTRIBUTING.md and GOVERNANCE.md.
Docs · Specification · Apache-2.0
Portable across tools. Shareable across teams.