How It Works

harness-kit has three main components and a plugin system. harness.yaml is the config format at the center of everything. The desktop app is a multi-section management console for it. The harness CLI is a standalone terminal tool that compiles it. Plugins — SKILL.md files, agents, hooks, scripts — run inside your AI tools.

harness.yaml

harness.yaml is the single declaration of your entire AI coding setup. It follows the Harness Protocol — an open, vendor-neutral specification.

plugins:
  - research@0.2.0
  - board@0.1.0
  - explain@0.2.0

mcp-servers:
  - name: memory
  - name: filesystem

instructions:
  operational: "Always create a feature branch. Never commit to main."
  behavioral: "Direct, concise. Lead with the answer."

permissions:
  tools:
    allow: ["Bash", "Edit", "Read"]
    deny: ["WebFetch"]
  network:
    allow: ["api.anthropic.com"]

env:
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

extends:
  - profiles/backend-engineer.yaml

The full schema supports version, kind, metadata, plugins, mcp-servers, instructions, permissions, env, and extends. Harness Protocol spec →

Desktop App

The desktop app is a management console organized into named sections. It reads your harness configuration, provides observability into what your AI tools are doing, and gives you direct control over the pieces that are hard to manage from a terminal.

CORE

• Harness — view and edit your harness.yaml, CLAUDE.md, plugins, MCP servers, and hooks in a structured UI
• Marketplace — browse and install plugins from the registry

INSIGHTS

• Observatory — session telemetry: every session, every tool call, token usage, timeline, trends

SYSTEM

• Security — permissions, secrets management, audit log

WORKFLOWS

• Board — AI-native Kanban board; each card can be handed to an autonomous agent that runs a five-phase LangGraph pipeline (spec → planning → coding → QA review → QA fix) locally on your machine, streaming live progress back to the card. See Agentic Task Execution.
• Roadmap — AI-generated quarterly roadmaps and competitor analysis tied to your board; features convert directly into board tasks

Standalone sections

• Agents — detection panel for AI coding agents installed on your machine
• Comparator — run the same prompt across Claude Code, Cursor, and Copilot side by side
• Harness Parity — after compiling, confirm the same plugins, MCP servers, and skills landed in each connected AI tool, and catch drift
• Command Palette — Cmd+K to navigate and operate the app; Ask AI reaches a local Ollama chat
• Memory — browse, search, and manage the knowledge graph your agents orient themselves in
• Services — live status dashboard for the four background servers; the title bar health dot links here

Background servers — four processes run inside the desktop app:

CLI

The harness CLI is a standalone terminal tool. You run it from your shell; it is not a plugin and does not run inside an AI tool's session.

harness validate          # check harness.yaml against the schema
harness compile           # compile harness.yaml into native per-tool configs
harness sync              # fetch plugins into local cache, write harness.lock
harness check             # detect drift between compiled output and harness.yaml
harness detect            # show which AI platforms are present in the working directory
harness scan              # security audit of installed plugin skill files

compile output — harness compile writes native configuration files for each detected AI tool: .claude/settings.json for Claude Code, .cursor/rules for Cursor, and so on. Each AI tool then loads those files at session start. This is how harness.yaml becomes active in your AI tools — it is compiled, not interpreted at runtime.

Plugin System

Lifecycle

/plugin install research@harness-kit

/research https://github.com/anthropics/claude-code

Plugin Anatomy

plugins/<name>/
├── .claude-plugin/
│   └── plugin.json       # name, version, description
├── skills/
│   └── <name>/
│       ├── SKILL.md      # the workflow (what the AI reads at invocation)
│       └── README.md     # human docs
├── scripts/              # optional: shell automation
├── hooks/                # optional: Stop, PreTool, PostTool handlers
└── agents/               # optional: isolated specialist subagents

SKILL.md vs. a prompt

A SKILL.md is a complete workflow specification, not a prompt template:

• Mandatory step ordering — steps execute in sequence, no skipping
• Input parsing rules — how to interpret arguments and flags
• Tool usage patterns — which tools to call, when, and how
• Output structure — exact format for results
• Error handling — explicit recovery steps when things fail
• Common mistakes table — known failure modes and fixes

This structure makes skills repeatable across sessions and transferable across users. The same /research invocation produces the same workflow regardless of who runs it.

Portability

Your harness is fully reproducible. Config files live in version control; plugins reinstall from the registry with the same commands.

Your harness.yaml serializes your whole setup. Share it, import it, or use it to bootstrap the same configuration on any machine.

/harness-export                       # capture plugins, versions, sources → harness.yaml
/harness-import harness.yaml          # interactive picker: teammate chooses what to install

(Available via the harness-share plugin.)

Design Philosophy

harness-kit is a framework without a runtime. No SDK, no build step, no execution layer to depend on. The framework is the config format and the portability it creates.

The SKILL.md is the portable unit. Plugins add distribution, versioning, and automation on top — but the workflow itself is plain text that any AI tool can read. Uninstall a plugin and nothing breaks, because nothing was ever coupled to it.

The spec is open. The format travels.