harness-kit

Portable configuration for AI coding tools.

Works with Claude Code · Cursor · GitHub Copilot

🧰 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

/plugin marketplace add harnessprotocol/harness-kit

Fallback: install with script (skills only)

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

📋 Browse all 16 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

🔄 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 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 for setup with 1Password, direnv, Google Secret Manager, and CI environments.

🖥️ Desktop App

A Tauri desktop companion that brings the harness concept to a native UI.

• Sync engine — compiles harness.yaml to platform configs
• Plugin explorer — browse and manage installed plugins
• Observatory — live session dashboard with stats and transcripts
• Comparator — side-by-side harness comparison with interactive terminal panes
• Harness editor — inline editing with custom profiles
• Memory — knowledge graph viewer via membrain integration
• Team chat — IRC-style chat backed by a self-hosted WebSocket relay

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.

📄 License

Apache 2.0