harness-kit

AI Agent Harness Kit

A project-agnostic harness that gives any AI coding agent (Claude Code, GitHub Copilot, Codex, Cursor, Gemini, …) a consistent operating contract: what to load, what sequence to follow, and how to iterate until done — plus autonomous, metric-driven self-improvement loops that can run on a local LLM, and a live metrics dashboard.

Extracted as a clean, reusable kit. See CREDITS.md for the prior work it builds on, and HARNESS_CARD.md for the one-page control/agency/runtime design summary.

New here? Run node scripts/harness/doctor.mjs (or npm run harness:doctor). It checks your runtime, shows what's available, runs the self-tests, and prints the exact MCP setup for your editor or agent — Claude Code, Cursor, VS Code, Windsurf, Cline, Zed, JetBrains, or a plain terminal. Per-environment recipes: docs/ENVIRONMENTS.md.

Install

The kit is packaged as an Agent Skill and a Claude Code plugin, so it installs into 70+ agents (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, …) without copying folders by hand.

# Any of 70+ agents, via the open Agent Skills CLI (-g installs globally for your user):
npx skills add <owner>/harness-kit -g

# A specific agent (or several):
npx skills add <owner>/harness-kit -g -a github-copilot -a claude-code

# Or from a local checkout of this kit:
npx skills add ./harness-kit --list      # discover, then add --skill harness to install

# Claude Code, via the native plugin marketplace (auto-updates):
/plugin marketplace add <owner>/harness-kit
/plugin install harness-kit

Two layers, on purpose. The skill above is the playbook — it teaches the agent the harness contract (stages, gates, loops, memory) and is enough for guidance in any repo. The runnable engine (the scripts/harness/*.mjs loop runners, dashboard, and MCP server) ships with the kit files; get it by either installing the Claude Code plugin (bundles everything) or adopting the kit scaffold per SETUP.md. Replace <owner>/harness-kit with wherever you publish this kit.

What's inside

Capability	Where	Notes
Workflow stage machine	.github/harness/HARNESS.md, .github/instructions/	Understand → Architect → Architect Challenge (cross-model) → Implement → Review (breadth+depth) → Feedback, with 5 architectural gates
Convergence loops	.github/harness/loops/, run-loop.mjs	Iterate until checks (lint/type/build/test) go green
Workflow loops	same	Rubric-graded passes (review-fix, feature-cycle, ci-green)
Experiment loops (autoresearch-style)	run-experiment.mjs, experiment-loop.mjs	Hill-climb a numeric metric; keep-if-improved, else revert
Local-LLM agents	ollama-agent.mjs, ollama-apply-agent.mjs	Drive loops with a local model via Ollama or LM Studio (--provider)
Memory	.github/harness/memory/	Committed lessons + Architecture Briefs (structure only — no lessons shipped)
Knowledge graph	graph-refresh-loop.mjs	Optional structural memory (needs the Understand-Anything plugin)
MCP server	mcp-server.mjs	Exposes 15 graph/memory/vector + loop/report tools over MCP (.vscode/mcp.json registers it)