harness-score: A Deterministic Scanner for AI Agent Harnesses
Your AI coding agent is only as reliable as the harness around it. Measure that harness in seconds with harness-score.
At a glance
- What is it?
- harness-score scores the filesystem scaffolding around an AI coding agent, from AGENTS.md to gate hooks, and returns a maturity level from L0 to L4. It is a static scanner, not a test runner, and its value depends on whether you agree with its check catalog.
- Who is it for?
- Adopt harness-score if you already use Cursor, Claude Code, Windsurf, Cline, or Continue and want a deterministic, CI-gateable number for harness coverage; skip it if you need functional verification of agent behaviour or if your guardrails live outside the repository tree. Before relying on it, run npx harness-score on a repository you know well and check whether the failed checks match gaps you recognize, then decide whether --min-level 4 is a gate you can actually hold.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: Agent Reliability Is a Harness Property, Not a Model Property
The README makes a claim that is easy to verify in practice and hard to act on: an AI coding agent is a model plus a harness, and two repositories using the same model can produce wildly different results because one has context files, rules, hooks, and guardrails and the other has none. The stated failure modes are concrete. An agent rediscovers conventions every session, deletes something it should not, or ships code nobody reviewed because nothing was positioned to catch it. harness-score exists to turn that vague unease into a number. It targets engineers who already run an agent in a repository and want to know which specific artifact is missing, not a general lecture on prompt quality. The README is explicit that the intended fix is not better prompting but a control system with guides, sensors, and guardrails, the same shape you would build around any autonomous process. That framing is the project's core opinion, and every check follows from it.
How the Scanner Works: Filesystem Facts, Six Dimensions, 108 Points
The mechanism is deliberately narrow. harness-score points at a repository, detects which AI coding tools are in use (the README names Cursor, Claude Code, Windsurf, Cline, and Continue), and evaluates 36 checks across six weighted dimensions totaling 108 points. Context and Guides is worth 20 points and covers AGENTS.md substance plus .cursor/rules/ scoping and frontmatter. Skills and Commands is 17 points for packaged procedures such as skills, slash commands, subagents, and trigger-worthy descriptions. Hooks and Guardrails is 14 points and distinguishes gate hooks, which block risky actions, from feedback hooks, which lint or format on edit. Sensors and Feedback is 20 points for test runner, linter, type checker, formatter, and the presence of actual test files. CI Feedback is 14 points for a pipeline that runs tests, lint, and types on every push, plus an installed pre-commit hook. Hygiene and Safety is 23 points for .gitignore, absence of leaked .env or secret files, a license, a lockfile, and safe MCP configuration. The README states that every check is a filesystem fact (a file exists, parses, or matches a pattern) and never a judgment call or network request, which is what makes the score reproducible across machines and suitable for gating a pipeline. There are no LLM calls in the scan path. The output is a maturity level, a per-dimension percentage, and a ranked list of failures, each naming the file and linking to a remediation recipe.
The Maturity Ladder Gates on Shape, Not Just Point Totals
The five levels are the part of the design most likely to be argued about. L0 Unharnessed means no orientation artifacts. L1 Documented requires a substantive AGENTS.md. L2 Guided adds scoped .cursor/rules/, at least one skill or command, and basic hygiene such as ignored env files. L3 Sensing requires a working feedback loop: test runner, linter, type checker, and CI re-verifying every push. L4 Self-correcting adds gate hooks that make destructive actions impossible rather than discouraged, plus feedback hooks that lint and format inline. The README is direct that levels gate on shape, not arithmetic: 80 points of documentation with zero tests is L1, not a high score. The scanner reports the blocking requirement for the next level in the form To reach L3: sensors >= 60%; ci >= 50%, so the path upward is stated rather than inferred. Whether those specific thresholds are the right ones is a judgment call the documentation does not defend in the material available; it presents them as the model, and you either accept the model or you do not. The L4 description is also the most ambitious claim in the README, since it asserts that a mistake would have to get past rules, hooks, tests, types, CI, and gates, mostly without a human. That is a statement about intended coverage, not a measured outcome.
Running It: One Command, No Configuration Required
The documented entry point is a single command run from the repository root: npx harness-score. The README shows the resulting output, which includes the tool version, the working directory, a maturity level and score line such as Maturity: L2 Guided Score: 70/108 (65%), the detected tools, a per-dimension bar with points, and a next-level hint. The example output is from v1.0.0 and shows Hooks & Guardrails at 0/14 points, which is the kind of specific gap the tool is designed to surface. Beyond npx, the README references a --min-level flag, used in the L4 row as gate CI on --min-level 4, which is the intended CI integration: fail the pipeline if the repository drops below a level. The package is published to npm and to JSR under @paladini/harness-score, and the repository ships a CI workflow at .github/workflows/ci.yml. The README does not document a configuration file, ignore list, or custom check mechanism in the material provided, so treat the check catalog as fixed unless the full documentation says otherwise. That is a constraint worth knowing before adoption: you configure the repository, not the scanner.
What It Deliberately Does Not Measure
The README includes a section on limits, and it is more honest than most. harness-score does not evaluate whether your tests are good, only that they exist, run, and gate. It does not evaluate whether your rules are true; a stale rule scores the same as a fresh one. It cannot verify functional correctness, since no static scan can confirm behaviour. It does not measure team practice, because branch protection and review culture live outside the repository tree. Those four exclusions define the tool's boundary. A repository can reach L4 with a test suite that asserts nothing meaningful, rules that contradict the codebase, and no branch protection at all, provided the filesystem artifacts are present and well-formed. The score measures coverage of a checklist, and the checklist is a proxy for reliability rather than a measurement of it. This is not a defect in a static scanner; it is the trade-off that makes the score deterministic and CI-gateable. But it means a rising number is evidence that the harness is more complete, not evidence that the agent is safer in any outcome sense.
Where It Fits Against Running the Agent and Reading the Diff
The obvious alternative is not another scanner; it is the workflow most teams already have, which is running the agent and reviewing its output by hand. That approach measures the real thing, since a human reads the diff and decides whether it is correct. It also scales badly, produces no comparable number across repositories, and cannot gate a pipeline. A second alternative is a conventional code quality tool such as a linter or coverage reporter. Those overlap with one dimension of harness-score, Sensors and Feedback, but they say nothing about AGENTS.md, scoped rules, skills, or gate hooks, because they were not built to look at agent scaffolding. The difference in approach is that harness-score scans for the presence and shape of harness artifacts, while a linter scans the code those artifacts are supposed to govern. They are complementary, and the README's own check catalog treats a linter as one input among 36. If your goal is to know whether the agent's last change was correct, harness-score will not answer that. If your goal is to know whether the repository gives the agent any chance of being correct, it will.
Maintenance, Release Cadence, and the MIT Licence
The release history in the material shows a steady cadence: v1.6.3 added Forgejo Actions CI detection, v1.6.4 addressed multilingual score documentation parity, and v1.6.5 made Devbox projects scan cleanly. Those are small, specific changes rather than architecture overhauls, which suggests the check catalog is stable and the work is in detection coverage. For adopters, that pattern matters in two ways. First, a scanner whose checks change between releases can shift your score without any change to your repository, so pinning a version in CI is the safe default rather than tracking latest. Second, the fixes are detection-oriented, meaning a repository that scored wrongly under an older version may score correctly after an upgrade, which is a reason to re-run after bumping rather than assuming the number is stable. The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained; it comes with no warranty. That is a permissive arrangement with few obligations, and it is the same licence used by a large share of the JavaScript ecosystem. This is a description of the licence terms, not legal advice; check the LICENSE file and your own counsel if the distinction matters to your organisation.
Editorial conclusion
Adopt harness-score if you already use Cursor, Claude Code, Windsurf, Cline, or Continue and want a deterministic, CI-gateable number for harness coverage; skip it if you need functional verification of agent behaviour or if your guardrails live outside the repository tree. Before relying on it, run npx harness-score on a repository you know well and check whether the failed checks match gaps you recognize, then decide whether --min-level 4 is a gate you can actually hold.
Community notes