HAR

Product Introduction

1. Definition: HAR (Harness) is an open-source, agent-agnostic framework for orchestrating multi-agent coding workflows. Technically, it is a deterministic workflow engine and MCP (Model Context Protocol) server that provides isolated execution environments for AI coding agents.
2. Core Value Proposition: HAR exists to solve the operational complexity of scaling from a single AI coding assistant to a trusted, parallel fleet of agents. It provides a standardized, verifiable, and observable infrastructure layer, enabling deterministic validation, artifact tracking, and collision-free concurrent development within any code repository.

Main Features

1. Machine-Readable Project Contract (.har/): HAR replaces scattered documentation (README, CLAUDE.md, CI configs) with a single, version-controlled contract in the .har/ directory. This contract defines the project's stack, launch commands, verification scripts, and environment needs in a structured format that any MCP-compatible agent (Claude Code, Cursor, etc.) can read and execute identically, ensuring consistency.
2. Deterministic Isolated Worktrees (Slots): The core isolation mechanism. For each task, HAR creates a dedicated "slot" (e.g., slot 1, slot 2). This involves branching from the main codebase into a separate Git worktree, allocating unique network ports, and provisioning isolated dependencies (like a dedicated test database). This prevents collisions between multiple concurrently running agents.
3. Verifiable Proof & Evidence Trail: HAR's verify stage runs the project's actual test suites and quality checks (e.g., unit tests, linters, type checks) within the isolated worktree. Crucially, it captures a cryptographic hash of the verified code tree and stores logs, artifacts, and pass/fail status. This creates an auditable evidence trail, allowing human reviewers to trust the agent's output based on proof, not promises.
4. Plugin Ecosystem for Extensible Verification: HAR's functionality is extended via plugins. These are framework-specific packages (e.g., for Playwright, RocketSim) that register pre-configured verification stages into the harness. This allows teams to easily add complex, standardized checks (like end-to-end browser tests) to their workflow without manual scripting.
5. Mission Control Dashboard: An optional, open-source local web dashboard that provides full-stack observability. It visualizes all repositories, active worktree slots, run histories, validation results, and generated artifacts in one place, offering centralized monitoring for multi-agent development sessions.

Problems Solved

1. Pain Point: Inconsistent and Drifting Agent Environments. Knowledge of how to run, build, and test a project is fragmented across various files, leading to silent failures when scripts fall out of sync with the actual codebase.
2. Pain Point: Concurrency Collisions in Multi-Agent Workflows. Multiple AI agents cannot work on the same repository simultaneously without interfering with shared resources like dev servers, databases, or Git state.
3. Pain Point: Lack of Trust in AI-Generated Code. Reviewers must manually re-run all checks to verify an AI agent's changes, negating the efficiency gains. There is no inherent, verifiable record of what was tested.
4. Target Audience: Engineering Teams adopting AI Coding Agents (e.g., teams using Cursor, Claude Code, or GitHub Copilot at scale); Open-Source Maintainers receiving AI-generated PRs; Platform Engineers building internal AI development tooling.
5. Use Cases: Parallelizing Code Reviews: Multiple agents can independently review different aspects of a PR simultaneously in isolated slots. Safely Generating Large Features: An agent can build a complex feature in an isolated branch, with full CI-like verification, before a human reviews the evidence and merges. Onboarding & Legacy Code Exploration: New team members or agents can use HAR to safely execute and test in a repository without breaking the main branch.

Unique Advantages

1. Differentiation: Unlike vendor-locked AI coding platforms, HAR is agent-agnostic and repository-native. Its contract lives in the repo, making workflows portable across any MCP-compatible agent (Claude, Cursor, Windsurf, etc.). This contrasts with proprietary sandboxes that tie you to a single provider.
2. Key Innovation: The "slot" abstraction combined with deterministic verification gates. HAR formalizes the ephemeral "developer environment" as a first-class, orchestratable object. By binding a successful verification to a specific, hashed code state, it creates a strong link between AI output and provable correctness, a concept missing from traditional CI and agent tools.

Frequently Asked Questions (FAQ)

1. How does HAR compare to traditional CI/CD like GitHub Actions? HAR is designed for the inner development loop with AI agents, providing immediate, isolated environments for active coding and experimentation. CI/CD systems like GitHub Actions verify code after it's committed. HAR runs the same checks before commit, within the agent's session, and provides the evidence to the developer. They are complementary: HAR can be configured to run a subset of checks quickly, with the full suite running later in CI.
2. Is HAR only for AI coding agents, or can developers use it? While built for agent orchestration, HAR's CLI and isolated worktree model is also highly useful for developers. It provides a clean, scripted way to spin up multiple concurrent feature environments locally, making it a powerful tool for manual development, testing, and debugging complex branches.
3. What is the performance overhead of creating isolated worktrees and databases? HAR uses Git worktrees, which are lightweight and share object storage with the main repository, minimizing disk overhead. For databases, it typically uses fast, containerized instances (e.g., via Docker) or managed ephemeral databases. The overhead is designed to be minimal compared to the cost of environment collisions and context switching.
4. Does HAR require me to rewrite my project's build or test scripts? No. HAR leverages your project's existing scripts (e.g., npm run test, make build). The .har/ contract simply points to these existing commands. The value is in standardizing how and in what context these scripts are invoked for an AI agent.
5. How does HAR handle stateful services or complex microservice architectures? HAR's plugin system and contract are extensible for complex setups. Plugins can be written to orchestrate Docker Compose environments, spin up dependent services, or manage cloud resources for a specific slot. The isolation principle applies at the architecture level, aiming to provide each agent slot with a fully functional, self-contained stack.