English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil) | Français
🩺 AI Harness Doctor
Your coding agent can sound confident while following stale repository instructions. AI Harness Doctor audits AGENTS.md, CLAUDE.md, Cursor rules, hooks, MCP settings, and related harness files before that drift becomes a broken PR.
It helps you consolidate scattered guidance into one human-owned AGENTS.md, keep tool-specific files as small pointers, and measure whether the resulting harness actually improves agent answers.
<p<a href="https://github.com/NieZhuZhu/ai-harness-doctor/actions/workflows/test.yml"<img align="left" alt="CI" src="https://github.com/NieZhuZhu/ai-harness-doctor/actions/workflows/test.yml/badge.svg"</a <a href="https://www.npmjs.com/package/ai-harness-doctor"<img align="left" alt="npm version" src="https://img.shields.io/npm/v/ai-harness-doctor.svg"</a <img align="left" alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" <img align="left" alt="Python 3.9+" src="https://img.shields.io/badge/Python-3.9%2B-blue.svg" <img align="left" alt="Node >=16" src="https://img.shields.io/badge/Node-%3E%3D16-green.svg"</p <br clear="left"
Evidence
- Fixing the harness measurably fixes the agent. In the reproducible before/after benchmark, consolidating a conflicted harness into one canonical AGENTS.md took objective agent answers from 6/28 to 28/28 correct, eliminated both flip-flop answers, and cut average latency by 27% and captured cost by 17% on identical tasks — methodology and raw results.
- It holds up on a real production repo. On trycompai/comp (an actively developed ~1.7k-star bun monorepo whose CLAUDE.md had forked from AGENTS.md and still taught stale npx commands), one treatment run took the agent from 18/24 to 24/24 correct — before treatment it echoed the stale doc verbatim, deterministically, in both runs — while cutting latency 37% and agent turns 45%; the boundary is mapped honestly by a published null result on openai/codex, whose healthy docs left nothing for treatment to improve — positive case · null case.
- The disease is real at the top of open source. A corpus of 14 well-known repositories (react, vscode, n8n, ollama, transformers, dify, supabase, gemini-cli, codex, home-assistant, zed, elasticsearch, cline, ghostty — 58k–247k stars, pinned as submodules) shows 10/14 already ship a root AGENTS.md, yet one deterministic batch scan still surfaces 96 gaps, 44 overlapping instruction files, 15 declaration-vs-code mismatches, and 3 same-scope conflicts across 150 agent-config files — corpus and per-repo results.
- Findings you can trust. 38 logged validation rounds against real repositories have produced fifteen false-positive fixes (openai/codex, microsoft/vscode, cline, gemini-cli, assistant-ui, …), each released with regression tests; deferred classes are logged openly instead of hidden — external validation log.
Start in 60 seconds
Run a zero-install, read-only checkup:
npx ai-harness-doctor scan .Explain which instructions apply to one path:
npx ai-harness-doctor explain . packages/api/src/handler.tsVerify the Node and Python runtime:
npx ai-harness-doctor doctor --self-testCheck which version npx resolved:
npx ai-harness-doctor --versionNothing above changes the audited repository.