Portable configuration for AI coding tools.
Works with Claude Code · Cursor · GitHub Copilot · Codex · OpenCode · Windsurf · Gemini CLI · Junie
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.
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 @harnessprotocol/cli # requires Node.js 24+Desktop App:
brew tap harnessprotocol/tap # skip if you already ran this above
brew install --cask harness-kitOr 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 nightlyNightly 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 | bashDownloads skill files to ~/.claude/skills/ over HTTPS. The full plugin experience (scripts, hooks, agents) requires the marketplace install.
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.
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
| 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
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 --yesRepository-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 --yesThe 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 allThe 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.yamlSee harness.yaml.example for the config format. New captures use Harness Protocol v2; v1 profiles continue to parse, compile, and reconcile.
Fail a pull request when compiled config files no longer match harness.yaml:
name: Harness
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: harnessprotocol/harness-kit@v0.13.1
with:
target: claude-code,cursor,agents-mdThe step exits 1 on drift and writes a table of the drifted files to the job summary. Run harness compile locally and commit the result to fix it.
| Input | Default | Meaning |
|---|---|---|
command |
check |
check compares compiled files with harness.yaml. status reports drift across detected tools. |
harness-file |
harness.yaml |
Path to the profile (check). |
target |
all | Comma-separated targets (check). |
baseline |
none | Team baseline harness.yaml in the checkout (status). |
cli-version |
the release version | npm version or dist-tag of the harness-kit npm package, for example latest. |
- 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.envinplugin.json) withrequired,optional, andsensitiveflags. 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.
A Tauri desktop app that shows what each AI coding tool on your machine has configured, and lets you copy a missing piece from one tool to another. It reads local files. No external service is needed.
- Machine is the home screen. A grid lists every MCP server, skill, instruction file and plugin across the tools it finds, with one column per tool. Click a cell to open a drawer that shows where the resource lives, how copies differ, and a copy action from one tool to another. Tools that are not installed are hidden until you choose "Show all".
- Drift is a view inside Machine. It compares your
harness.yamlwith the files compiled from it, shows a diff for each item, and previews a fix before writing anything. - Profile edits
harness.yamland compiles it into a project. With no project chosen, Profile and Compile use your personal~/.harness/harness.yaml(the CLI uses the same file;~/.claude/harness.yamlis read only if that is absent). With a project chosen in the title bar, they use that project's committedharness.yamlas the team baseline. - Claude Code holds the editors for that tool: Instructions, MCP servers, Plugins, Hooks, Permissions, and Usage (sessions, tool calls and tokens read from
~/.claude). - Marketplace browses the plugin catalog.
- Settings holds preferences, secrets and the activity log.
- Comparator runs the same prompt across tools side by side. It is off until you turn it on in Settings under Labs.
How it handles your files:
- Copies, Compile and Drift fixes show a preview before they write. Backups and rollback points for files in your home folder go to
~/.harness/backups/, and for a project to that project's.harness/backups/. - The app has no shell access. Folder choices, plugin imports and exports use native dialogs.
- Security presets merge into your permissions and list any deny rule they would remove before writing.
- Dialogs trap focus and return it on close, menus work from the keyboard, and text colors meet WCAG AA contrast.
To build or run it, see CONTRIBUTING.md (pnpm dev:desktop). Design rules are in apps/desktop/DESIGN.md. The desktop app is a separate product from the plugin marketplace.
- Claude Code — native plugin marketplace support
- Cursor — SKILL.md files work as prompt instructions;
/harness-compilegenerates native config - GitHub Copilot — reads
CLAUDE.mdnatively viachat.useClaudeMdFile
See the Harness Protocol spec for the full cross-platform target mapping.
- 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, andSOUL.mdwith separation of concerns - Understanding Agents — AGENT.md, custom subagents, and "AI agent" disambiguation
See CONTRIBUTING.md for plugin guidelines, skill conventions, and PR process.
- General — contact@harnesskit.ai
- Security — security@harnesskit.ai (see SECURITY.md)