Model or dataset
wquguru/harness-books avatar
wquguru/harness-books

harness-books: the argument is about consequences, not answer quality

📚 Two books on harness engineering — the design philosophies behind Claude Code & Codex: constraints, query loops, context governance, multi-agent verification. harness-books.agentway.dev

3,246 stars382 forksPythonLicense varies

At a glance

What is it?
Two books on what holds a coding agent in place once it is inside terminals, repositories, permission systems, and team workflows. One reads Claude Code's runtime structure, the other compares it against Codex, and both are readable online with PDF exports.
Who is it for?
Start with the first book if you are building or operating an agent harness and want the runtime frame, and go straight to the comparison if you are choosing between existing systems and already know the vocabulary. Two things to know before you lean on it.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • wquguru/harness-books3,246 ★ · +166
Star history
Repository2026-09-102026-11-15
wquguru/harness-books3.1k3.2k

166 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The framing question is about consequences

Both books pursue a single question, stated in the opening lines: once a code-writing model is placed inside terminals, repositories, permission systems, and team workflows, what keeps the overall system bounded, continuous, and accountable for consequences. That last word carries the argument. The books explicitly do not walk through source code line by line, and the stated concern is how a harness organises constraints and execution and how an unstable model is folded into a sustainable engineering order. The parts they treat as belonging to the same body are prompt layering, query loops, permission decisions, context governance, failure recovery, multi-agent verification, local rules, and team institutions. The risk they name is not that a model says something wrong once, but that a system has no structure for handling what happens when it does.

The core claims are five sentences long

The claims are compact enough to quote, which is a sign the authors think they are load-bearing. Harness engineering is about how constraint structures organise execution. Once a model enters a real engineering environment, the main problem is no longer answer quality but behavioural consequences. Prompts, tools, permissions, state, recovery, verification, and institutions are not accessories around the system but organs in the same control structure. When comparing agent systems, the key question is not the feature checklist but where order is actually placed. And if a team cannot turn individual experience into reusable rules, it will struggle to turn an agent into a stable system. The last claim is the one aimed at organisations rather than at systems, and it is the thread both books pick up in their later chapters.

Book 1 treats prompt as part of the control plane

The first book uses Claude Code as its observation target and concentrates on runtime structure: why a system eventually has to grow a control plane, a query loop, tool permissions, context governance, recovery paths, multi-agent verification, and team rules. Its chapter titles are written as arguments rather than topics. Chapter 2 says prompt is not personality, prompt is the control plane. Chapter 3 calls the query loop the heartbeat of an agent system. Chapter 4 asks why agents cannot touch the world directly, covering tools, permissions, and interrupts. Chapter 5 treats context as a budgeting regime, naming memory, a project instruction file, and compaction as the three places that budget is spent. The questions the book promises to answer sharpen the same point: why this is not prompt engineering at larger scale, and why a model mistake should be treated as a runtime norm rather than an exceptional event.

Recovery and verification are deliberately separate chapters

Two chapters in the first book deal with failure, and they are kept apart on purpose. The book lists as one of its questions why multi-agent work and verification should not be blended into one vague mechanism, and the chapter titles make the separation visible: one chapter covers errors and recovery, framed as building a system that keeps working after failure, and the next covers multi-agent work and verification, framed as managing instability through division of labour. The argument underneath is that a model failing is normal operation, so the structure that responds to failure has to be designed rather than improvised. The last content chapter turns outward, covering team adoption as the process of turning a smart tool into a reusable institution, which is the organisational half of the argument that the opening question set up.

Book 2 compares where each harness puts order

The second book places Claude Code and Codex side by side and asks a narrower question than the first: where does each harness place order. The description is candid about the shape of the difference, saying one path starts from runtime discipline and the other from a more structured control layer, and that both systems work while distributing authority differently. The promised questions are specific. What the biggest control-plane divergence is between the two. How to align the roles of query loops, threads, rollouts, and state. What governance work permissions, sandboxes, and policy languages are actually doing. And how skills, hooks, and local rules encode organisational habits into the system. There is also a practical question aimed at people building their own harness: who to learn from first, and which layer to study first.

Three ways in, including a two-chapter shortcut

The reading paths are given explicitly, which is a courtesy most technical books skip. If you want the whole frame, read the first book and then the second. If you already work with coding-agent tools and want the architectural split directly, start with the second book. And if you only want the conclusions, the recommendation is to read chapter 9 of the first book together with chapter 7 of the second, which is the shortest defensible path through the material. The first book's chapter 9 is its ten principles, so the shortcut lands on the summary rather than on an arbitrary middle chapter. Three appendices extend the first book further: checklists that turn principles into executable constraints, diagrams of the runtime skeleton, and a source map recording which files ground each chapter.

The repository is the manuscript, and it carries no licence

The layout matches a publishing project rather than a code project. Each book is a directory holding its own chapters under a locales tree, with the English files named after the chapter titles, and there is a tools directory plus an assets directory for whatever the site build needs. A Chinese README sits beside the English one at the root, and two agent configuration directories are present along with both a project instruction file and an agents file, which suggests the authors worked on the text with the tools the books describe. Two practical notes for anyone planning to cite or reuse this. The licence field is recorded as unknown and there is no licence file at the root, so the text carries no stated grant. And there are no GitHub releases, with the most recent push dated 2026-04-19, so the site's own build is the only distribution channel for both the online version and the PDF exports.

Editorial conclusion

Start with the first book if you are building or operating an agent harness and want the runtime frame, and go straight to the comparison if you are choosing between existing systems and already know the vocabulary. Two things to know before you lean on it. The material is descriptive rather than a source walk, so it will not tell you which files to edit in either tool. And the repository carries no licence file, so read for ideas rather than borrowing the text.

Frequently asked questions

What are the two harness books?

Harness Engineering: A Design Guide to Claude Code, and The Harness Design Philosophies of Claude Code and Codex. The first uses Claude Code as an observation target and concentrates on runtime structure, while the second compares the two systems and asks where each harness places order.

Do the harness books cover source code?

No. They are explicitly not meant to walk line by line through source code. They focus on how a harness organises constraints and execution, covering prompt layering, query loops, permission decisions, context governance, failure recovery, multi-agent verification, local rules, and team institutions.

Can I read only part of the harness books?

Yes. The suggested paths are to read Book 1 then Book 2 for the full frame, to start with Book 2 if you already know coding-agent tools, or to read just Book 1 Chapter 9 and Book 2 Chapter 7 if you only want the conclusions.

What licence covers the harness books?

The repository records the licence as unknown and contains no licence file at the root. Both books are readable online and offer PDF exports from the project site, and there are no GitHub releases.

Official sources

  1. Issues
  2. Project website
  3. README
  4. wquguru/harness-books on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/wquguru-harness-books.svg)](https://hysenlabs.com/projects/wquguru-harness-books)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/wquguru-harness-books.svg)](https://hysenlabs.com/projects/wquguru-harness-books)

Was this useful?