harness-kit

Portable configuration for AI coding tools.

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, install, 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	Layered code explanations for files, functions, directories, or concepts	/explain src/auth/
research	Process any source into a structured, compounding knowledge base	/research https://...
review	Code review with severity labels and cross-file analysis	/review
lineage	Column-level data lineage through SQL, Kafka, Spark, and JDBC	/lineage orders.amount
rubber-ducky	Cross-model second opinion on your plans and code before you commit	/rubber-ducky

📋 Browse all 17 plugins → 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

🔄 Port Your Whole Harness

Capture the native configuration you already use, reconcile it with personal, project, session, and organization policy, then apply it to any supported harness. Preview is the default; conflicts and unsupported capabilities block writes until you make an explicit choice.

harness-kit capture --scope project
harness-kit capture --scope project --yes --force
harness-kit reconcile harness.yaml --target all --json
harness-kit apply harness.yaml --target codex --yes
harness-kit rollback --yes

Repository-local skills can be promoted without moving them first: either pin their existing owner/repo/path source or package their declared files into a content-addressed capsule.

harness-kit skills discover
harness-kit skills promote ./skills/review --mode reference --yes
harness-kit skills promote ./skills/review --mode capsule --scope personal --yes

The organization workflow is currently a release preview pending managed and self-hosted contract certification. Enrolled devices use the same engine for staged updates: optional updates stay in preview, while a policy-mandated update applies without a second consent prompt, verifies convergence, reports health, and restores the prior transaction on failure.

harness-kit auth login
harness-kit org rollout-sync <organization-id> --target all

The existing plugin-oriented workflows remain available:

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 all eight supported targets
/harness-sync	Keep supported tool configs aligned
/harness-validate	Validate a Harness Protocol profile

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 for the config format. New captures use Harness Protocol v2; v1 profiles continue to parse, compile, and reconcile.

🔒 Security & Privacy

• Local by default — Harness Kit does not upload local source material. An enrolled organization may receive a client-redacted inventory of assignments, digests, target state, and drift; raw files, prompts, skill bodies, secret values, and environment contents are excluded on-device.
• Local state stays local — reconciliation bases, ownership fingerprints, device assignments, backups, and rollback manifests live under a self-ignoring .harness/ directory.
• 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. Harness Kit does not persist, transmit, or log detected secret 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 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
• Fleet and Drift — layered capture/apply previews, capability losses, reconciliation conflicts, governed rollout status, and local rollback history
• Security — permissions editor, secrets management, and audit logging

See 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 — What is this, why do I need it, how does it work
• Plugins vs. Skills — Why everything ships as a plugin, even when it's just a prompt
• Claude Conventions — 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 for plugin guidelines, skill conventions, and PR process.

📬 Contact

• General — contact@harnesskit.ai
• Security — security@harnesskit.ai (see SECURITY.md)

📄 License

Apache 2.0