Deterministic · Offline · Framework-agnostic
A coding agent is only as good as the repository it works in. Harness Doctor scans for the structure that keeps agents from guessing, reports what's missing, and scores the repo 0–100 so you can watch it improve.
$ bunx --bun @andypai/harness-doctor@latest ✔ AGENTS.md found — short and map-like ! docs/ exists but AGENTS.md never points into it ✘ 3 unused exports, 1 circular import ──────────────────────────────────────── Harness score 82/100
No model calls. No network. The same repo always produces the same score.
Two lenses on a repo, both deterministic — the kind of thing you could answer with
ls and wc -l, made rigorous.
Reads your repository off disk — its files, layout, and docs. Does an agent
entry-point exist? Is it a short map or a 600-line wall of text? Does it actually
point into docs/? Is your pnpm setup hardened against supply-chain
attacks?
Finds unused files, unused exports, unused dependencies, and circular imports — the cruft that misleads an agent reading your codebase and quietly drags the score down.
Every finding comes with a one-line explanation of what's wrong and a concrete fix — written to be read by a human or handed straight to a coding agent.
From the root of any project.
Get a score and a list of findings. Add --verbose for file and line
numbers.
Wire it into your agent's workflow so it reads findings, fixes them, and keeps the score from sliding.
Emit a versioned report. Key automations off plugin/rule and
schemaVersion, not prose.
Scan every pull request and leave findings inline. For hardened CI, pin
@v1 to a full commit SHA and let Dependabot or Renovate bump it.
name: Harness Doctor on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pull-requests: write issues: write jobs: harness-doctor: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: abpai/harness-doctor@v1
Drop a harness.config.ts at your project root. Turn rules up, down, or off.
// harness.config.ts import type { HarnessDoctorConfig } from "harness-doctor/api"; export default { deadCode: true, docsContract: true, rules: { "harness-doctor/docs-structure/spec-contract-exists": "error", }, } satisfies HarnessDoctorConfig;
Run it once on any repo and see where it stands.