better-harness: the package excludes the docs directory the readme points at
An open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.
At a glance
- What is it?
- QoderAI/better-harness scores the workflow around a coding agent rather than its diff, across five named dimensions, and ships six host plugins. Its most interesting sentences are the ones refusing to overclaim, and its packaging quietly drops the install guide from the tarball.
- Who is it for?
- better-harness is unusual in the current field because it spends its documentation on what it cannot know. It says a passing check proves an intervention was exercised rather than that anything improved, it says its own trend view shows recorded movement rather than causal proof, it labels its inspector demo as fictional data, and it notes that appearing in the readme is a display choice rather than a support claim.
- 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 10 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- QoderAI/better-harness2,479 ★ · +186
| Repository | 2026-09-17 | 2026-11-21 |
|---|---|---|
| QoderAI/better-harness | 2.3k | 2.5k |
186 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The package excludes the directory the readme points at
The readme tells you that the extra hosts keep their installation steps and boundaries in the installation guide, and gives that guide a repository path inside the documentation folder's own nested folder. The published package includes the documentation folder, then negates thirteen paths inside it: the nested documentation folder itself, the translation folder, the source folder, the static assets, the scripts, the build output, the cache directory, the dependency directory, a vendor directory, the site configuration, the sidebar definition, and the site's own two package files. So the file the readme points a reader to for per-host installation is inside one of the excluded paths. That is not necessarily wrong, since the guide is also published on the project site, but it means the readme and the tarball disagree about where the instructions live.
Six plugin directories and no single entrypoint
The readme is explicit that this project does not have one entrypoint across every host, and that you should pick the host you already use to get its exact installation, verification, invocation and report-output steps. The tree backs the claim up rather than merely asserting it: there are six plugin directories in the repository, one each for several coding agents, plus a separate extension manifest for one more host and a hosted plugin entry. The manifests differ because the hosts differ, and the output differs too. Two of the hosts produce a report in the host's own native canvas component, while five produce a self-contained HTML file with a Markdown file beside it. That difference is the practical consequence of no shared entrypoint: the artefact you get depends on which agent you already pay for.
The demo data is fictional and the document says so
Two demos are offered and both carry a disclosure. The interactive inspector follows a product intention through agent activity, sessions, files and commits in a read-only workspace and keeps evidence strength and limitations visible, and the caption under it says the sample is fictional English data and that it never reads your workspace. The history view is described with equal care: it shows how the five dimensions move over time, and the note underneath says the static final frame summarises recorded reports and shows trends rather than causal proof of improvement. For a tool whose entire pitch is evidence, having both demo artefacts volunteer their own limitations is the most persuasive thing in the readme, and it is also the fastest way to judge whether the honesty extends to the code.
A passing check is explicitly not proof of improvement
The methodological statement sits in the middle of the readme and is worth quoting rather than paraphrasing. The project says it is deliberately honest in that unobserved behaviour stays explicit instead of becoming an unsupported score or claim, and that passing a current check proves the intervention was exercised while only a comparable later result can prove the loop improved. That single distinction is the difference between a dashboard and an evaluation. It also sets the bar for adoption: you need two comparable runs of the same task before the tool will claim anything, which means you need a task you intend to run more than once, and a baseline you captured before you changed anything in the process itself.
Five dimensions, each a question and a list of what backs it
The evaluation model is a table of five rows, and every row is phrased as a question with the evidence types named beside it. Task understanding asks whether the agent knows the goal and what done means, backed by rules, the agent instruction file, specs and a design document. Controlled execution asks whether work is on supported repeatable paths, backed by skills, commands, tool-protocol servers and sandbox boundaries. Change validation asks whether there is evidence the change works, backed by tests, linting, hooks and observable diagnostics. Reliable delivery asks whether speed bypasses quality checks, backed by human review, approvals, pipelines and recovery paths. Learning capture asks whether the next task benefits from this one, backed by loop discovery, reusable skills and memory. The framework around it is a two-part loop borrowed from published writing on harness engineering: guidance available before work starts, and signals available after the agent acts.
The homepage field points at the readme, not at the site
The manifest is tidy in ways that are worth reading as intent. The published package version matches the newest tag, both an alpha-suffixed seventh minor. It is an ES module workspace of five packages, split between the harness itself, a studio, a user interface, a desktop application and the studio's own apps, so this is a product with a desktop shell rather than a single command. Its keywords include the vendor's own name and a host-specific package identifier, which tells you who it is for. And its homepage field points at the readme in this repository, while the readme's own navigation points at the published documentation site, so the two files disagree about where the front door is.
Its own configuration directory is committed here
The tree carries a configuration directory named after the project itself, alongside the agent instruction file, the design document, two roadmaps, a hook directory, a model directory, a prompt directory, a reference directory, a skills directory, templates, case studies, scripts and assets. Two test configurations sit at the root, one for local runs and one for continuous integration, which is a sign that the suite is slow enough to want a different budget on the build servers. The two roadmap files are the item to watch: one undated and one carrying a year in its name, and nothing in the readme says which one is authoritative. A plugin scanner configuration sits next to them, presumably for checking that the six host manifests stay in step.
Editorial conclusion
better-harness is unusual in the current field because it spends its documentation on what it cannot know. It says a passing check proves an intervention was exercised rather than that anything improved, it says its own trend view shows recorded movement rather than causal proof, it labels its inspector demo as fictional data, and it notes that appearing in the readme is a display choice rather than a support claim. That candour is the reason to read it. The practical caveats are equally clear. There is no universal entrypoint, so installation is per host. And the npm package excludes the documentation subtree that the readme sends you to for those per-host steps, so keep the repository rather than the tarball if you are following the readme literally.
Frequently asked questions
What does QoderAI better-harness measure?
The workflow around a coding agent rather than its diff, across five dimensions: task understanding, controlled execution, change validation, reliable delivery and learning capture. Each dimension is phrased as a question and paired with the evidence types that back it, from instruction files and specs through tests, hooks, approvals and memory.
Which coding agents does better-harness support?
Six hosts are set up in the README with two more named in the installation guide. Two of the six produce a report in the host's own native canvas component, and five produce a self-contained HTML report with a Markdown file beside it. The README notes that appearing in it is a display choice rather than a support-level claim.
How does better-harness avoid overclaiming improvement?
It scopes behaviour claims to the task episodes and project mechanisms it observed, keeps missing evidence explicit rather than scoring it, and says a passing current check proves only that the intervention was exercised. Only a comparable later result is treated as proof that the loop improved.
Is the better-harness installer the same on every host?
No. The README says there is no universal entrypoint across hosts and tells you to pick the host you already use for its exact installation, verification, invocation and report-output steps. The per-host guides live in the repository documentation and on the project site.
What is in the better-harness npm package?
The six host plugin directories, a hosted plugin entry, an extension manifest, the agent instruction and governance files, case studies, hooks, models, prompts, references and skills. The documentation directory is included with thirteen paths inside it excluded, including the nested folder the README links to for per-host installation steps.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/qoderai-better-harness)Star history chart for your README
[](https://hysenlabs.com/projects/qoderai-better-harness)Was this useful?