Mechanical constraints for AI agents. Ship faster without the chaos.
AI coding agents are powerful, but unreliable without structure. Left unconstrained, they introduce circular dependencies, violate architectural boundaries, and generate drift that compounds across a codebase. Teams respond with code review backlogs and manual checklists — trading agent speed for human bottlenecks.
Harness Engineering takes a different approach: mechanical enforcement, not hope.
Instead of relying on prompts and conventions, harness encodes your architectural decisions as machine-checkable constraints. Agents get real-time feedback when they violate boundaries. Entropy is detected and cleaned automatically. Every rule is validated on every change.
For tech leads and architects: Scale AI-assisted development across your team with confidence. Define constraints once, enforce them everywhere — across agents, developers, and CI.
For individual developers: Stop babysitting your AI agent. Give it guardrails and let it execute. Spend your time on design decisions, not cleanup.
- Cross-Platform Support — Fully tested on Windows, macOS, and Linux with mechanical enforcement preventing platform-specific regressions
- Context Engineering — Repository-as-documentation keeps agents grounded in project reality, not stale training data
- Architectural Constraints — Layered dependency rules enforced by ESLint, not willpower
- Agent Feedback Loop — Self-correcting agents with peer review and real-time validation
- Entropy Management — Automated detection of dead code, doc drift, and structural decay
- Implementation Strategy — Depth-first execution: one feature to 100% before the next begins
- Key Performance Indicators — Measure agent autonomy, harness coverage, and context density
npm install -g @harness-engineering/cli
harness generate --globalThis installs the CLI, the MCP server, and writes slash commands and agent definitions to your global config directories (~/.claude/commands/, .gemini/ etc.). Once generated, every project on your machine has access to /harness:* slash commands, agent personas, and the harness-mcp server binary — no per-project setup needed.
Tip: Re-run
harness generate --globalafter updating the CLI (harness update) to pick up new or changed skills.
In an AI agent session (Claude Code, Gemini CLI):
/harness:initialize-project
The initialization skill walks you through project setup interactively — name, adoption level, framework overlay — and scaffolds everything including MCP server configuration.
CLI alternative (for scripts or CI):
harness init --name my-project --level intermediate
/harness:verify
Runs all mechanical checks in one pass — configuration, dependency boundaries, lint, typecheck, and tests.
CLI alternative:
harness validate && harness check-deps
git clone https://github.com/Intense-Visions/harness-engineering.git
cd harness-engineering/examples/hello-world
npm install && harness validate| Package | Description |
|---|---|
@harness-engineering/types |
Shared TypeScript types and interfaces |
@harness-engineering/core |
Validation, constraints, entropy detection, state management |
@harness-engineering/cli |
CLI: validate, check-deps, skill run, state show |
@harness-engineering/eslint-plugin |
11 rules: layer violations, circular deps, forbidden imports, boundary schemas, doc exports, no nested loops in critical paths, no sync IO in async, no unbounded array chains, no unix shell commands, no hardcoded path separators, require path normalization |
@harness-engineering/linter-gen |
Generate custom ESLint rules from YAML configuration |
@harness-engineering/graph |
Knowledge graph for codebase relationships and entropy detection |
@harness-engineering/orchestrator |
Agent orchestration daemon for dispatching coding agents to issues |
import { validateConfig } from '@harness-engineering/core';
import { HarnessConfigSchema } from '@harness-engineering/cli';
const result = validateConfig(configData, HarnessConfigSchema);
if (!result.ok) {
console.error('Validation failed:', result.error.message);
process.exit(1);
}# CLI — validate project constraints
harness validate
# Check architectural dependency boundaries
harness check-deps
# Run a skill
harness skill run harness-verificationSee Getting Started for a full walkthrough.
Harness enforces a strict layered dependency model. Each layer may only import from layers below it.
graph TD
A[agents] --> S[services]
S --> R[repository]
R --> C[config]
C --> T[types]
style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
style S fill:#50b86c,stroke:#2d7a3e,color:#fff
style R fill:#f5a623,stroke:#c17d12,color:#fff
style C fill:#9b59b6,stroke:#6c3483,color:#fff
style T fill:#7f8c8d,stroke:#566573,color:#fff
Violations are caught at lint time via @harness-engineering/eslint-plugin — not at code review.
Install the CLI, MCP server, skills, and personas so they're available in every project:
npm install -g @harness-engineering/cli
harness generate --globalThe single npm install -g provides both the harness CLI and the harness-mcp server binary, with all dependencies version-matched. harness generate --global then writes to your global config directories:
| Platform | Slash Commands | Agent Definitions |
|---|---|---|
| Claude Code | ~/.claude/commands/ |
.claude/agents/ |
| Gemini CLI | .gemini/customCommands/ |
.gemini/agents/ |
After this, /harness:* slash commands and harness agent personas are available in every conversation — no per-project install needed.
For real-time constraint validation, connect the MCP server to your project. The easiest way is during initialization:
/harness:initialize-project
This scaffolds your project and configures the MCP server automatically.
To add the MCP server to an existing project:
harness setup-mcpThis gives your AI agent access to 46 tools (validation, entropy detection, skill execution, state management, code review, graph queries, and more) and 8 resources (project context, skills catalog, rules, learnings, state, graph, entities, relationships).
Manual MCP setup
Claude Code — add to .mcp.json in your project root:
{
"mcpServers": {
"harness": {
"command": "harness-mcp"
}
}
}Gemini CLI — add to .gemini/settings.json in your project root:
{
"mcpServers": {
"harness": {
"command": "harness-mcp"
}
}
}Then add your project directory to ~/.gemini/trustedFolders.json (Gemini ignores workspace MCP servers in untrusted folders):
{
"/path/to/your/project": "TRUST_FOLDER"
}Note:
harness-mcpis installed alongside the CLI bynpm install -g @harness-engineering/cli. Using the installed binary instead ofnpx @harness-engineering/mcp-serveravoids stale npx cache issues and ensures the MCP server uses the same package versions as the CLI.
| Client | MCP Config Location | Additional Setup |
|---|---|---|
| Claude Code | .mcp.json |
None |
| Gemini CLI | .gemini/settings.json |
Add project to ~/.gemini/trustedFolders.json |
| Component | Count | Description |
|---|---|---|
| Packages | 7 | Core library, CLI, ESLint plugin, linter generator, graph, orchestrator, shared types |
| Skills | 79 | Agent workflows across 3 tiers: workflow, maintenance, and domain catalog |
| Personas | 12 | Architecture enforcer, code reviewer, planner, verifier, task executor, and 7 more |
| Templates | 6 | Base, basic, intermediate, advanced, Next.js, and orchestrator scaffolds |
| Examples | 3 | Progressive tutorials from 5 minutes to 30 minutes |
Learn by doing. Each example builds on the previous:
| Example | Level | Time | What You Learn |
|---|---|---|---|
| Hello World | Basic | 5 min | Config, validation, AGENTS.md — see what a harness project looks like |
| Task API | Intermediate | 15 min | Express API with 3-layer architecture enforced by ESLint |
| Multi-Tenant API | Advanced | 30 min | Custom linter rules, Zod boundary validation, personas, full state lifecycle |
Getting Started
- Getting Started Guide — From zero to validated project
- Day-to-Day Workflow — Full lifecycle tutorial using slash commands
- Best Practices — Patterns for effective harness usage
- Agent Worktree Patterns — Running multiple agents in parallel
Core Concepts
- The Core Principles — Foundational concepts behind harness engineering
- Implementation Guide — Adoption levels and rollout strategy
- KPIs — Measuring agent effectiveness
Reference
- CLI Reference — All commands and flags (for CI/scripts)
- Configuration Reference —
harness.config.jsonschema
| Project | Key Contribution |
|---|---|
| GitHub Spec Kit | Constitution/principles, cross-artifact validation |
| BMAD Method | Scale-adaptive intelligence, workflow re-entry, party mode |
| GSD | Goal-backward verification, persistent state, codebase mapping |
| Superpowers | Rigid behavioral workflows, subagent dispatch, verification discipline |
| Ralph Loop | Fresh-context iteration, append-only learnings, task sizing |
These five projects most directly shaped harness engineering. See the full Inspirations & Acknowledgments for all 42 projects, standards, and tools analyzed — what we adopted, what we skipped, and why.
See CONTRIBUTING.md for development setup, coding standards, and pull request guidelines.
MIT License — see LICENSE for details.