Harness Kit

harness-kit

Portable configuration for AI coding tools.

[](https://github.com/harnessprotocol/harness-kit/releases) [](https://github.com/harnessprotocol/harness-kit/actions/workflows/validate.yml) [](https://github.com/harnessprotocol/harness-kit/actions/workflows/build.yml) [](LICENSE) [](.claude-plugin/marketplace.json) [](CONTRIBUTING.md)

Works with Claude Code · Cursor · GitHub Copilot · Codex · OpenCode · Windsurf · Gemini CLI · Junie

🧰 What is harness-kit?

Your AI coding setup — plugins, skills, MCP servers, hooks, conventions — packaged into a single config you can apply to any tool on any machine. Build it once, share it with your team in one file.

📦 Install

Skills & Plugins (Claude Code):

/plugin marketplace add harnessprotocol/harness-kit

CLI (harness validate, compile, sync, ...):

brew tap harnessprotocol/tap && brew install harness-kit
# or: npm install -g @harness-kit/cli  # requires Node.js 22+

Desktop App:

brew tap harnessprotocol/tap  # skip if you already ran this above
brew install --cask harness-kit

Or download the .dmg directly from the latest release and drag Harness Kit.app to /Applications. Note: the app is not notarized — right-click and select Open on first launch.

Nightly builds (latest main, rebuilt daily — may be unstable)

brew tap harnessprotocol/tap  # skip if already added
brew install harnessprotocol/tap/harness-kit-nightly          # CLI nightly → installs as harness-kit-nightly
brew install --cask harnessprotocol/tap/'harness-kit@nightly' # desktop nightly

Nightly builds track the tip of main and are rebuilt every day at midnight UTC. Use them to get the latest features before a stable release — at the cost of stability guarantees.

Fallback: install skills with script (no Node required)

If your Claude Code build doesn't support the plugin marketplace:

curl -fsSL https://raw.githubusercontent.com/harnessprotocol/harness-kit/main/install.sh | bash

Downloads skill files to ~/.claude/skills/ over HTTPS. The full plugin experience (scripts, hooks, agents) requires the marketplace install.

⚡ Quick Start

Install explain — no dependencies, works in any codebase:

/plugin install explain@harness-kit

Then try it:

/explain src/auth/middleware.ts       # explain a specific file
/explain the payment processing flow  # search the codebase for a concept
/explain src/services/                # map a directory

Produces a layered explanation: summary, key components, how it connects, patterns, gotchas, and where to start if you need to change it.

🔌 Plugins

A few highlights to get started:

| Plugin | What it does | Try it | |--------|-------------|--------| | [explain](plugins/explain/skills/explain/README.md) | Layered code explanations for files, functions, directories, or concepts | /explain src/auth/ | | [research](plugins/research/skills/research/README.md) | Process any source into a structured, compounding knowledge base | /research https://... | | [review](plugins/review/skills/review/README.md) | Code review with severity labels and cross-file analysis | /review | | [lineage](plugins/lineage/skills/lineage/README.md) | Column-level data lineage through SQL, Kafka, Spark, and JDBC | /lineage orders.amount | | [rubber-ducky](plugins/rubber-ducky/skills/rubber-ducky/README.md) | Cross-model second opinion on your plans and code before you commit | /rubber-ducky |

> 📋 [Browse all 17 plugins →](.claude-plugin/marketplace.json) or run /plugin marketplace browse harness-kit

🌍 Community

| Plugin | Author | What it does | |--------|--------|-------------| | superpowers | Jesse Vincent | TDD, systematic debugging, brainstorming-before-coding, subagent delegation, git worktree isolation |

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@obra

🔄 Share Your Setup

Export your plugin setup to a harness.yaml, commit it to your dotfiles, and restore it anywhere.

| Command | What it does | |---------|-------------| | /harness-export | Write harness.yaml from your current setup | | /harness-import harness.yaml | Interactive wizard — pick what to install | | /harness-compile | Compile to native configs for Claude Code, Cursor, and Copilot | | /harness-sync | Keep all three tools' configs aligned | | /harness-validate | Validate against the Harness Protocol v1 schema |

Shell fallback (no Claude Code required)

curl -fsSL https://raw.githubusercontent.com/harnessprotocol/harness-kit/main/harness-restore.sh | bash -s -- harness.yaml

See [harness.yaml.example](harness.yaml.example) for the config format. harness.yaml follows the Harness Protocol v1 open spec — a vendor-neutral format for portable AI coding harnesses.

🔒 Security & Privacy

• No telemetry, no data collection — harness-kit never phones home. Optional stats are local-only.
• Secrets stay out of config — plugins declare environment variables they need (requires.env in plugin.json) with required, optional, and sensitive flags. Values live in your shell profile, direnv, or a secrets manager — never in checked-in files. The framework validates existence but never reads or logs values.
• Plain text, fully inspectable — plugins are markdown and JSON. No binaries, no background processes, no network calls on install. Scripts and hooks only run when you explicitly invoke a skill.
• Granular permissions — tool-level allow/deny/ask, path-level write restrictions, and network host allowlists. All configurable per-project.
• Audit logging — permission changes, secret access, and preset applications are logged with timestamps.
• Prompt injection detection — the research plugin treats all external content as untrusted, scanning for injection attempts before processing.

See the [Secrets Management guide](website/content/docs/guides/secrets-management.md) for setup with 1Password, direnv, Google Secret Manager, and CI environments.

🖥️ Desktop App

A Tauri desktop control plane for your AI coding harnesses — config console with reverse-import and drift-repair. No external services required for any core path.

• Sync engine — compiles harness.yaml to platform configs
• Plugin explorer — browse and manage installed plugins
• Marketplace — embedded plugin browser for discovering and installing from the marketplace
• Observatory — live session dashboard with stats and transcripts, reading local ~/.claude data
• Comparator — structured evaluation workbench: configure harnesses, run side-by-side comparisons, review file diffs, and judge results across a 4-phase workflow, local-only
• Harness editor — inline editing with custom profiles
• Parity — cross-platform feature parity tracking across AI coding tools
• Security — permissions editor, secrets management, and audit logging

See [apps/desktop/](apps/desktop/) for build instructions. The desktop app is a separate product from the plugin marketplace.

🌐 Cross-Platform

• Claude Code — native plugin marketplace support
• Cursor — SKILL.md files work as prompt instructions; /harness-compile generates native config
• GitHub Copilot — reads CLAUDE.md natively via chat.useClaudeMdFile

See the Harness Protocol spec for the full cross-platform target mapping.

📚 Docs

• [FAQ](docs/FAQ.md) — What is this, why do I need it, how does it work
• [Plugins vs. Skills](docs/plugins-vs-skills.md) — Why everything ships as a plugin, even when it's just a prompt
• [Claude Conventions](docs/claude-md-conventions.md) — Organizing CLAUDE.md, AGENT.md, and SOUL.md with separation of concerns
• Understanding Agents — AGENT.md, custom subagents, and "AI agent" disambiguation

🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for plugin guidelines, skill conventions, and PR process.

📬 Contact

• General — [contact@harnesskit.ai](mailto:contact@harnesskit.ai)
• Security — [security@harnesskit.ai](mailto:security@harnesskit.ai) (see [SECURITY.md](SECURITY.md))

📄 License

[Apache 2.0](LICENSE)

Source & license

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

• Author: harnessprotocol
• Source: harnessprotocol/harness-kit
• License: Apache-2.0
• Homepage: https://harnesskit.ai

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