Chachamaru127/claude-code-harness: A Structured Loop for Agent-Driven Development
Claude Code is powerful, but raw agent work drifts. Plans live in chat history, tests become optional, review happens too late, and release evidence gets rebuilt from memory rather than verified fact. For teams shipping production code, this drift creates real risk: scope creep, untested paths, and releases that can't be reproduced from source.
Chachamaru127/claude-code-harness solves this by wrapping a disciplined operating loop around Claude Code's agent capabilities. Instead of open-ended conversation, you get a repeatable path: write the spec and plan, implement only the approved slice, verify the result, review independently, and package evidence for PR or release. With 2,973 GitHub stars, 289 forks, and an MIT license, this Go-native tool has gained traction among developers who want agent assistance without sacrificing engineering rigor.
What is Chachamaru127/claude-code-harness?
Chachamaru127/claude-code-harness is a development harness—a workflow framework and command surface that enforces structure on AI-assisted coding. Built primarily in Shell with a Go-native guardrail engine, it installs as a Claude Code plugin and replaces the default "ask the agent to code" pattern with a Plan → Work → Review → Ship cycle.
The project is maintained by Chachamaru127 and last committed on 2026-07-14. It claims a critical distinction: "Claims in this README are machine-checked against the code." CI gates verify that implemented components are actually wired, that the task ledger's dependencies stay consistent, and that shipped binaries rebuild from source. A feature is described only after a gate proves it is reachable—"written" is not "working."
This matters because the AI tooling space is flooded with promising demos that collapse under real use. Harness explicitly rejects that pattern. It supports Claude Code v2.1+ as its primary path, with internal-compatible adapters for Codex CLI, OpenCode, and Cursor, plus candidate-level exploration for Grok and GitHub Copilot CLI. The support boundary is strict: a host only moves up when Harness has its own bootstrap, trigger, runtime, and release evidence.
The harness also surfaces decision-making for non-engineer stakeholders through three single-screen HTML views: Plan Brief (understanding, options, risks before implementation), Progress (WIP/TODO/done counts with drift alerts), and Acceptance (per-criterion pass/fail with ship/wait/reject recommendation).
Key Features
Five core verbs, 22 total skills. The harness keeps its surface small: plan, work, review, sync, release. These map to concrete commands (/harness-plan, /harness-work, /harness-review, /harness-release) that operate on documented file artifacts.
Source-of-truth planning. /harness-plan drafts or updates spec.md and Plans.md with scope, acceptance criteria, dependencies, unknowns, and stop conditions. Data the agent has not seen stays explicitly marked as unknown rather than silently invented—a direct countermeasure to hallucination drift.
Non-trivial plan validation. For complex work, Harness records team_validation_mode and validates the plan through team/sub-agent or manual-pass perspectives for spec/Plans alignment, memory reuse, product fit, security fit, and works-in-practice verification.
TDD-enforced implementation. /harness-work executes approved tasks with test-driven development when required, runs verification, and keeps work inside the plan boundary. The /harness-work all variant runs the full approved plan through implementation and review paths.
Independent review gate. /harness-review separates review from implementation and treats major findings as blockers—not suggestions. This prevents the common anti-pattern where an agent "reviews" its own work and approves it.
Release evidence packaging. /harness-release checks release readiness, CHANGELOG/tag boundaries, and evidence packaging only after implementation and review are complete. PR ready is explicitly not release ready.
Migration safety. bin/harness doctor --migration-report inventories old plugin caches, Codex skills, OpenCode files, symlinks, and memory state without deleting data—critical for teams evaluating adoption without breaking existing workflows.
Use Cases
Production feature development with traceability. Teams shipping regulated or audited code need evidence that requirements were specified, implemented, tested, and reviewed. Harness's artifact chain (spec.md → Plans.md → code + tests → review verdict → release pack) provides this by design, not by after-the-fact documentation.
Multi-developer coordination on agent-assisted projects. When multiple developers use Claude Code in the same repository, plans in individual chat sessions diverge. Harness's file-based source of truth (spec.md and Plans.md checked into version control) creates a shared contract that survives session boundaries. The optional harness-mem companion extends this to cross-session memory when configured.
Onboarding engineers to AI-assisted workflows. New team members often struggle with open-ended agent prompting—what to ask, how to verify, when to stop. Harness's bounded commands and explicit gates provide guardrails. The "First 15 Minutes" documentation routes users through install, setup, a small plan, and a single task execution before they encounter complexity.
Non-engineer stakeholder visibility. The three HTML decision surfaces (Plan Brief, Progress, Acceptance) let product managers or executives judge state without reading code. This bridges a persistent gap in AI-assisted development: technical progress is opaque to decision-makers.
Migration from experimental AI setups. Teams with scattered Claude plugins, Codex skills, OpenCode experiments, or Cursor configurations can run bin/harness doctor --migration-report to inventory state before committing to a unified workflow.
Installation & Setup
Harness offers tool-specific installation routes. The supported path is Claude Code v2.1+.
Claude Code (Supported)
claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup
After installation, verify with your first plan:
/harness-plan Improve the README onboarding flow
This command generates spec.md and Plans.md drafts for your review and approval.
Alternative Tool Routes
| Tool | Tier | Command |
|---|---|---|
| Codex CLI | internal-compatible | scripts/setup-codex.sh --user |
| OpenCode | internal-compatible | scripts/setup-opencode.sh |
| Cursor | internal-compatible | scripts/setup-cursor.sh |
| Grok | candidate | scripts/setup-grok.sh |
The README is explicit: "runtime parity is not claimed" for OpenCode, and "workflow smoke and Claude hook parity not claimed" for Grok. Do not assume identical behavior across hosts.
First 15 Minutes Workflow
- Install through your tool route.
- Run
/harness-setupor the equivalent setup script. - Run
/harness-planwith a small request; Harness writes thespec.mdandPlans.mddrafts. - Approve the generated contract or reply with corrections.
- Run the smallest approved task, e.g.,
/harness-work 1.1.1. - Run
/harness-reviewand retain the verification output.
Your role is not to hand-write the plan—it is to approve or correct the generated contract before execution continues.
Real Code Examples
The README provides direct command examples rather than extensive code snippets. These are reproduced exactly with explanatory context.
Example 1: Installing the Plugin
claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup
This three-step sequence activates the harness within Claude Code. The /plugin marketplace add command registers the plugin source, /plugin install loads it into the active session, and /harness-setup installs project guidance, command surfaces, hooks, and checks to establish a known baseline. Without this final setup step, the workflow commands (/harness-plan, /harness-work, etc.) are not available.
Example 2: Creating Your First Plan
/harness-plan Improve the README onboarding flow
This is the entry point for all harness work. The command takes natural language intent and produces two artifacts: spec.md (the specification with scope, acceptance criteria, unknowns, and stop conditions) and Plans.md (the task breakdown with dependencies). The user must approve or correct these before any implementation occurs. This single command embodies Harness's core principle: plan before work, and verify the plan before executing it.
Example 3: Executing an Approved Task
/harness-work 1.1.1
Tasks in Plans.md are hierarchically numbered. This command executes only the approved slice 1.1.1, adding tests when required by the plan, running verification, and keeping work inside the boundary. The granularity matters: you cannot accidentally implement unapproved scope because the harness references the plan file as source of truth.
Example 4: Running the Full Plan
/harness-work all
Use this only after the plan is clear and the repository baseline is known. It runs the approved plan through implementation and review paths automatically. The README warns this is for mature plans, not initial exploration—scope drift is more likely when the full plan hasn't been validated incrementally.
The README does not currently provide additional code examples beyond these command invocations. The tool's interface is command-driven rather than library-based, so traditional "code snippet" documentation is less applicable.
Advanced Usage & Best Practices
Validate non-trivial plans explicitly. The team_validation_mode for complex work is not optional ceremony—it catches misalignment between spec and Plans, identifies memory reuse opportunities, and flags security or product-fit issues before implementation begins.
Use /harness-work all cautiously. The full-plan execution is efficient only when the plan quality is high and the repository state is stable. For new domains or unclear requirements, stick to /harness-work with specific task IDs to maintain tight feedback loops.
Run the migration report before any cleanup. bin/harness doctor --migration-report is read-only by design. It inventories stale state without deleting it, giving you visibility into what would break before you make changes.
Treat auto-approve as experimental and currently non-functional. The HARNESS_AUTO_APPROVE=on flag exists but only records enablement in the orchestration ledger. Approval prompts are not skipped. The README explicitly gates full automation on Phase 101 governance verification that is not yet complete. Do not rely on this for unattended operation.
Consider harness-mem for cross-session continuity. The optional companion provides project-scoped memory, but purge remains explicit—you control when state is cleared rather than the system making invisible retention decisions.
Comparison with Alternatives
| Aspect | Chachamaru127/claude-code-harness | Raw Claude Code | Generic Agent Frameworks |
|---|---|---|---|
| Planning discipline | Enforced via spec.md/Plans.md |
Ad-hoc, chat-based | Varies; often manual |
| Review separation | Independent /harness-review gate |
Same-session, same-agent | Rarely structured |
| Release evidence | Packaged, verified, reproducible | Rebuilt from memory | Typically ad-hoc |
| Multi-tool support | Claude (supported), Codex/OpenCode/Cursor (internal-compatible), Grok (candidate) | Single-tool | Often tool-agnostic but shallow |
| Non-engineer visibility | Three HTML decision surfaces | None built-in | Rare |
| Machine-checked claims | CI gates verify reachability | N/A | Uncommon |
Raw Claude Code offers maximum flexibility but minimal guardrails—ideal for exploration, risky for production. Generic frameworks like [INTERNAL_LINK: LangChain for workflow orchestration] provide building blocks but require substantial custom engineering to achieve equivalent structure. Harness occupies a middle ground: opinionated enough to prevent drift, but bounded enough to stay maintainable. The trade-off is reduced flexibility for unconventional workflows—if your process doesn't fit Plan→Work→Review→Ship, you'll fight the tool.
FAQ
What Claude Code version is required? Claude Code v2.1+ for the supported path. Earlier versions are untested.
Is Node.js required? No. The guardrail engine is Go-native. Node.js is not a dependency.
Can I use this with Codex or Cursor?
Yes, but as internal-compatible tiers. Runtime parity with Claude is not claimed. Use scripts/setup-codex.sh or scripts/setup-cursor.sh.
What license applies?
MIT License. See LICENSE.md in the repository.
How do I check if my existing setup conflicts?
Run bin/harness doctor --migration-report. It reads without deleting.
Does auto-approve actually skip approval prompts?
No. HARNESS_AUTO_APPROVE=on currently records enablement only. Approval prompts remain. Full automation is deferred pending governance verification.
Is harness-mem required? No. It's optional for cross-session memory when configured and healthy.
Conclusion
Chachamaru127/claude-code-harness addresses a specific, painful gap in AI-assisted development: the drift between powerful agent capabilities and disciplined engineering practice. It does not replace Claude Code—it structures it. For teams already shipping with Claude Code who have felt the pain of untracked plans, missing tests, or late-breaking review issues, the harness offers a concrete upgrade path.
The tool is best suited for: teams with existing Claude Code adoption, organizations needing traceable development artifacts, and projects where plan quality matters more than implementation speed. It is less suited for rapid prototyping where flexibility outweighs repeatability, or for teams primarily using unsupported tools.
With 2,973 stars and active maintenance, the project has demonstrated traction. The machine-checked claims and explicit support boundaries suggest sustainable development rather than hype-driven growth.
Ready to add discipline to your agent workflow? Start at https://github.com/Chachamaru127/claude-code-harness.
