Harness Score CLI
A CLI that rates the maturity of an AI agent harness in a repository from L0 to L4: 36 file checks with no model calls or network.
- 619 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The scan only reads repository files and makes no network calls; writes are limited to reports and badges requested by explicit flags.
Install
- Works in
Manual install
npx harness-scoreNo install needed. For repeated runs use npm install -g harness-score or --save-dev.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The scan only reads repository files and makes no network calls; writes are limited to reports and badges requested by explicit flags.
This is third-party code. Review the repository files before installing.
What it does
Harness Score scans a repository and measures the harness around an AI agent: context files, rules, skills, hooks, tests and guards against dangerous actions. The result is a maturity level from L0 to L4 and a score out of 108 across six dimensions: context and guides, skills and commands, hooks and guardrails, feedback sensors, CI, and hygiene and safety. All 36 checks rest on filesystem facts: a file exists, parses or matches a pattern. There are no language-model calls and no network access, so the same commit gets the same score on a laptop and in CI. For every failed check the report names the file, says what is missing and links to a fix recipe, while the "To reach L3" line shows what blocks the next level. The tool recognizes harnesses for Cursor, Claude Code, Windsurf, Cline, Continue, Codex and Devin. Output comes as text, JSON, Markdown, an SVG badge and a share card. The --diff flag compares runs, --min-level sets a CI threshold, and a GitHub Action runs the scan on every push. A separate plugin adds a /harness-audit command and a harness-engineering skill to Cursor so the agent can close the gaps itself.
Who it is for. Teams that run repositories with Cursor, Claude Code or Codex and want to measure the reliability of the agent's environment as a number and hold it in CI.
Good fit when
- A repository has AGENTS.md and rules, and you want to know what is still missing before tests, a linter and hooks.
- Before rolling agents out to a team you need a baseline and a list of priority fixes.
- A pipeline must fail when harness maturity drops below a set level.
- Two repositories on the same model behave differently and their harnesses need comparing.
- A README needs a maturity badge that CI refreshes on its own.
Not a fit when
- You need to judge test quality or the truth of the rules: the tool sees only the presence and shape of files, and a stale rule scores like a fresh one.
- You need to assess agent behavior or functional correctness: a static scan cannot do that.
- You need branch protection, review culture and team practice that live outside the file tree.
Example request
Run harness-score in the project root and show what blocks moving from L2 to L3.Limitations
The score shows that infrastructure for reliable agent work exists, not that the work is reliable. The scan cannot tell good tests and correct rules from bad ones.
The tree is walked in full, but files over 512 KiB are not read, and with more than a million files, a symlink out of the root or an unreadable path the snapshot is marked incomplete and the exit code is 2.
The Claude Code and Windsurf plugins are in progress; the main plugin today is for Cursor.
How to disable. npx leaves nothing in the project. A global install is removed with npm uninstall -g harness-score, and the GitHub Action step is deleted from the workflow.
FAQ
What do levels L0 to L4 mean?
L0 has no harness, L1 a substantive AGENTS.md, L2 adds scoped rules and at least one skill, L3 working tests, a linter and CI, and L4 hooks that block dangerous actions and format edits.
Does the tool send data over the network?
No. The scan makes no network requests and calls no models. Zero runtime dependencies and determinism are permanent commitments by the author.
How do I add it to CI?
Add a paladini/harness-score@v1 step and optionally the badge parameter. A level threshold is set with --min-level; exit code 1 means the threshold was not met.
Which agents does the rating cover?
Repositories using Cursor, Claude Code, Windsurf, Cline, Continue, Codex and Devin: any of the signals counts under OR semantics.
How does the plugin differ from the CLI?
The plugin adds a /harness-audit command and a harness-engineering skill to Cursor so the agent fixes gaps itself. The CLI only measures and reports.
Discussion
No questions or reviews yet.
Related
CLI toolsHooks for Claude Code and Codex CLI keep a ledger of agent actions and refuse a "done" claim until a check has passed.
A 0 to 10 score for CLAUDE.md and AGENTS.md: Reporails finds vague rules, repeats and broken imports
A skill runs a third-party coding-agent harness through 30 benchmark tasks and compares pass rate, cost and speed.
An evaluation harness for coding agents: 26 compact tasks in 6 languages in Docker containers, weighted score and integrity checks
A local debugger for TypeScript agents: run step trees, CI trajectory checks and portable evidence bundles, with no account.
A CLI that finds traces coding agents leave in code, like filler comments, swallowed errors and fake imports, and scores it 0–100
README in short
The README opens with the thesis that an agent is a model plus a harness, shows sample output and the maturity ladder. It then covers the six dimensions, an honest list of what the tool does not measure, versioning rules, the four project components, badges and install options.