agentharness

Portable engineering policies for coding agents

Git, testing, logging, and language conventions written once and referenced everywhere — instead of re-authored (and drifting) in every project's own CLAUDE.md. One source of truth for the rules your coding agents follow, across every project you run them in.

npm: agentharness-toolkit ↗ GitHub ↗

Status: early — see the repo's MANIFEST.md for what exists today and ROADMAP.md for what's planned.

Why not just CLAUDE.md?

A single project's CLAUDE.md works fine — until there's a second project, and its CLAUDE.md quietly diverges: a different coverage bar, a branch-naming rule that contradicts the first repo's, a logging convention nobody remembers deciding. Multiply by N projects and the conventions aren't really policies anymore — just N independent guesses that happen to overlap.

agentharness fixes that specific problem: one CLAUDE.md router plus a set of skills and convention docs that every project's own (short) CLAUDE.md references. You still write a project-specific CLAUDE.md; it just stops being where the shared rules live.

Before — copy-pasted and drifted

<!-- project-a/CLAUDE.md -->
## Testing
Aim for 80% coverage. Use pytest.
Don't mock the database.

<!-- project-b/CLAUDE.md, six months later -->
## Testing
Try to keep coverage reasonable
(70%+ ok for now). pytest preferred.

After — one source, referenced

<!-- both projects, identical -->
## Testing
See agentharness's
patterns/testing/COVERAGE_REQUIREMENTS.md
for the coverage bar by rigor tier.
This project is Production tier.

What makes it different

Most agent configuration is advisory — conventions a model is expected to follow, with no mechanical enforcement. agentharness layers in three governance mechanisms that most coding-agent setups lack:

Opt-in publish authority

Agents verify and stage work locally, then stop and ask before pushing, opening a PR, or auto-implementing a recommendation. Full remote-write authority requires an explicit flag file or per-task instruction — work that's only staged locally is never "complete."

Enforced completion gate

Before an agent can declare done, it runs a completion check verifying lint, types, tests, coverage, and content quality in one shot. A Stop hook enforces it — the agent cannot end its session until the gate exits 0.

Review & merge mandates

Merging on CI green alone is not enough. The mandate requires fetching issue-level and inline PR comments, verifying each finding against current code, fixing what's real, and replying to every comment — closing the "agent silently ignored review feedback" failure class.

Client support

The harness is built for and dogfooded in Claude Code, and has also been tested with Codex CLI, Gemini CLI, and GitHub Copilot. Generators produce an always-on routing file plus an Agent-Skills-standard skill index for every major agentic coding tool:

Platform	Always-on file	Status
Claude Code	`CLAUDE.md`	✅ built + dogfooded
Codex CLI	`AGENTS.md`	✅ built + tested
OpenCode / Zed	`AGENTS.md`	⚠️ passively covered
Gemini CLI / Antigravity	`GEMINI.md`	✅ built + tested
GitHub Copilot	`.github/copilot-instructions.md`	✅ built + tested
Kilo Code	`.kilo/rules/agentharness.md`	✅ built, not live-tested
Cursor	`.cursor/rules/agentharness-router.mdc`	✅ built, not live-tested

No telemetry No background processes Linux & macOS Symlink / copy / submodule / npm modes

Quick start

Via npm — runs the lifecycle CLI (init / plan / status / doctor / audit / update / uninstall) with no separate clone step:

npx agentharness-toolkit init /path/to/your-project

Or via git clone:

git clone https://github.com/andr-ca/agentharness.git ~/agentharness
~/agentharness/tools/setup/harness-link.sh init /path/to/your-project

Preview without changing anything with --dry-run (or run plan instead of init), and verify afterward with doctor. Opt into the trunk-protection git hook with --with-hook, or a generated coverage-enforcing pre-push hook with --with-coverage-hook.