Chachamaru127/claude-code-harness

Claude Code Harness – A disciplined AI‑driven development loop

What it is – A Go‑native plugin that lets Claude Code (and compatible agents such as Codex, Cursor, Grok) take over the full software‑development cycle: planning, implementation, review, synchronization, and release. You give a high‑level intent (e.g., “Improve the README onboarding flow”); the harness turns it into a concrete specification (spec.md, Plans.md), runs the selected AI model(s) to write code, validates the output, and finally packages a clean release. Every step is gated by an explicit human approval step, so the tool is a safety‑oriented orchestration layer rather than a fully autonomous coder.

---

Core concepts & workflow

Step	Command	What it does	Human gate
Plan	/harness‑plan <intent>	Generates a specification (spec.md) and a task list (Plans.md) describing scope, acceptance criteria, dependencies, unknowns, and stop conditions.	You must approve or edit the generated contract before any code is written.
Work	`/harness‑work [task	all]`	Executes the approved tasks using the appropriate model (Claude Sonnet 5 for ordinary work, GPT‑5.6 Luna for high‑throughput “Breezing”, etc.). Handles solo or team execution, runs required tests, and iterates up to a configurable correction limit.
Review	/harness‑review	Runs a separate reviewer model (Claude Sonnet 5 at xhigh effort) that checks the changes, runs additional verification, and reports major findings.	Findings that block completion must be resolved before moving on.
Sync	/harness‑sync	Compares the current repository state with the original plan, flags drift, and updates the plan status.	You confirm any needed re‑planning.
Release	/harness‑release	Packages verified changes into a changelog, creates a git tag, and publishes a release.	A pre‑flight checklist must pass; otherwise the release is aborted.

The loop can be repeated automatically with /harness‑loop, which cycles through work‑review‑sync until a stop condition (e.g., max cycles, no runnable tasks) is met.

---

Safety & guardrails

• Two‑layer protection – a lightweight Go engine enforces runtime floors (5 categories covering billing, network egress, secret reads, production deploys, destructive ops) and a richer guardrail set (R01‑R16) that can deny, warn, or require confirmation for risky actions.
• Explicit approvals – operations that need pre‑approval (e.g., pushes to main, writes to protected paths) are recorded at plan time with expiry, scope, and usage limits.
• Unknown handling – any data the model has not seen is marked unknown rather than fabricated, preventing silent hallucinations.
• Session roster – when multiple agents work on the same repo, a local roster shows active sessions and allows verified message passing between them, with optional content verification.
• Non‑engineer view – three single‑page HTML dashboards (Plan Brief, Progress, Acceptance) let a stakeholder review the work without reading code.

---

Installation (30 seconds)

# From inside Claude Code (or any supported host)
claude /plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup

For other hosts (Codex CLI, Cursor, Grok) see the “Install by tool” table in the README – each provides a small shell script that adds the plugin and runs /harness‑setup.

---

Typical use case

1. Define intent – /harness‑plan "Fix duplicate orders; the same order must be stored only once."
2. Approve spec – Review spec.md/Plans.md and confirm acceptance criteria.
3. Run implementation – /harness‑work all (or target a single task with /harness‑work 3).
4. Automated testing & correction – The model runs the tests, reports failures, and iterates up to the configured correction limit.
5. Independent review – /harness‑review produces a separate audit; any major findings block the release.
6. Sync & release – /harness‑sync ensures the plan matches reality, then /harness‑release creates a tagged release with a generated changelog.

---

Model routing & effort levels

Role	Default model	Effort
Difficult decisions / advice	Claude Fable 5.1	high
Ordinary implementation	Claude Sonnet 5	medium
Dedicated reviewer	Claude Sonnet 5	xhigh
Codex work & review	GPT‑6 astra / GPT‑5.6 luna	xhigh / max

You can override any role or effort manually; the tool respects the explicit choice.

---

Project status & community

• License – MIT
• Supported hosts – Claude Code (v2.1+), Codex CLI, Cursor, Grok (all marked supported). Other tools are listed as candidate or future.
• Documentation – extensive docs covering onboarding, install routes, safety parity, model policies, and advanced capabilities (Breezing, harness‑loop, harness‑mem, etc.).
• Contributing – open to issues and PRs; see CONTRIBUTING.md.

---

TL;DR

Claude Code Harness is a safety‑first orchestration plugin that lets you harness Claude‑based agents (or compatible LLMs) to plan, code, verify, and ship changes in a repository, with every major step gated by a human review. It provides a clear, repeatable loop, strong guardrails, and multi‑tool support, making AI‑augmented development both powerful and controllable.