nexu-io/harness-engineering-guide: A Documentation Repository for AI Agent Runtimes
🔧 The open guide to Harness Engineering — concepts, tutorials, papers, tools, and resources for building and managing AI agent runtimes.
At a glance
- What is it?
- This is a curated guide repository, not a library or framework. It defines the harness as the runtime wrapper around a language model and collects articles, patterns and code examples for building one. The value is in the table of contents; the risk is that a guide ages faster than the runtimes it describes.
- Who is it for?
- Adopt this guide if you are building or evaluating an agent runtime and want a structured reading list that separates the harness layer from the framework layer. Do not adopt it if you need an installable dependency, a stable API surface, or versioned docs tied to a specific release.
- 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 150 days 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 Gap Between a Model and an Agent
A language model on its own returns text. It cannot call a function, read a file, or remember what happened in the previous turn unless something outside the model arranges it. The README names that something a harness: the runtime wrapper that turns a bare model into an agent, handling tool execution, memory, context assembly and safety boundaries. The guide is written for the people who build that layer rather than the people who consume it. That audience is narrower than it first appears. If you call an existing agent product through its API, you never touch a harness. If you are writing the loop that decides when to call a tool and when to stop, you are the target reader. The repository itself is a documentation project, not a runtime. The primary language listed is TypeScript, but the README's own walkthrough promises a working harness in 50 lines of Python, so the code samples are not confined to one language. Treat the language field as describing the site tooling, not the examples.
What the Repository Actually Contains
The README is a table of contents with short descriptions, organized into five groups. Getting Started holds three articles: what a harness is, a first harness in about 50 lines, and a decision tree comparing a raw harness against LangChain or CrewAI. Core Concepts covers the agentic loop (think, act, observe, with turn budgets, parallel tool calls and loop detection), the tool system (registry, static versus dynamic loading, MCP, tool description quality), memory and context (two-tier memory with daily logs plus long-term storage, and named file patterns), and guardrails (permission models, trust boundaries, sandboxing, prompt injection defense). The Practice group is the largest and the most opinionated: context engineering with priority-based assembly and token budgeting, sandbox setups on Docker and Firecracker, a skill system built around on-demand loading and a SKILL.md format, sub-agents using a leader-worker pattern with file-based communication, error handling with checkpoint and resume, multi-agent orchestration patterns, scheduling via cron and heartbeats, long-running harness design, managed agent architecture, and several articles on evaluation. Reference holds an implementation comparison across OpenClaw, Claude Code, Codex, Cline, Aider and Cursor, plus a glossary. Showcase holds two post-mortems attributed to the maintainer's own product work. There are no releases listed, so there is no versioned snapshot to pin against.
The Design Positions the Guide Takes
Several article titles encode arguments rather than neutral surveys, and those are the most useful part of the index. The skill-system article pairs on-demand loading with the phrase thin harness plus thick skills, which is a position: keep the runtime small and push capability into loadable units. The long-running harness article names context anxiety and self-evaluation bias as failure modes and proposes context reset versus compaction, with a generator-evaluator split borrowed from GANs. The managed agents article describes brain, hands and session as decoupled components, with credential isolation and a pets-versus-cattle framing for session state. The classifier-permissions article proposes replacing approval fatigue with model-based classifiers in a two-layer defense. The eval-infrastructure article claims that resource configuration alone can swing benchmark scores by six percentage points and argues for floor-plus-ceiling enforcement. These are specific, checkable claims. The guide is more valuable where it commits to a mechanism than where it lists options.
Getting the Guide, Not Installing It
There is no package to install. The README points to harness-guide.com as the hosted site, with a Chinese-language mirror at harness-guide.com/zh/ and a README.zh-CN.md in the repository. To read the source, clone the repository and open the files referenced in the tables, for example guide/what-is-harness.md, guide/your-first-harness.md or guide/agentic-loop.md. The homepage field in the repository metadata is empty, so the site URL comes from the README rather than from the repository configuration. Contributions go through the issue chooser: open a new issue, pick the Submit a Resource template, and fill in the title, URL and relevance. Direct pull requests are also accepted, with CONTRIBUTING.md as the stated reference. Discussion happens in GitHub Discussions, on Twitter at @nexudotio, and in a Feishu group linked from the README. The README also offers a BibTeX entry for citation, with the year given as 2026 and the author listed as Nexu Team.
Documentation That Tracks a Moving Target
The central limitation is structural. A guide about agent runtimes has no compiler to catch it when the field moves. The repository shows no releases, so there is no changelog telling you which article was revised after which runtime changed its tool-calling format. The last push timestamp is the only freshness signal available, and it tells you nothing about individual files. The implementation comparison article is the most exposed: it compares six named tools, and any of them can change its permission model or context handling between the article's last edit and the moment you read it. The same applies to anything describing MCP or specific sandbox configurations. A second limitation is scope. The guide defines the harness layer and repeatedly argues for keeping it thin, which means it is least useful to someone who has already chosen a framework and wants to configure that framework. The harness-versus-framework article is a decision aid, not a migration guide. A third issue is that the Showcase entries are the maintainer's own product post-mortems, so they read as primary sources about one company's pipeline rather than independent case studies. That is not disqualifying, but it changes how much weight to give the numbers in them.
Where This Sits Against Framework Documentation
The obvious alternative is the documentation of a framework such as LangChain or CrewAI, which the guide itself names in its decision-tree article. The difference in approach is what each one optimizes for. Framework documentation describes one concrete implementation: here are the classes, here are the parameters, here is the upgrade path when we break an interface. It is authoritative about that framework and silent about everything else. This guide inverts that. It describes the layer underneath all of them, which is why it can discuss tool registries, loop detection and context assembly without committing to a vendor, and why it can compare six implementations side by side. The cost of that generality is that nothing in it is guaranteed to run. A framework's docs come with a version number and a test suite. A guide comes with prose. If your question is how do I make this specific library do X, the framework docs win. If your question is what should the runtime around my model actually do, and which of these six tools made which trade-off, the guide is the better starting point. Reading both is the realistic path: use the guide to decide the shape of the harness, then use framework docs for the concrete implementation.
Licence and Maintenance Expectations
The repository is MIT licensed. For a documentation project that means you can copy the articles and code examples into your own materials, including commercial ones, provided you keep the copyright notice and permission notice. The README's stated intent, code you can copy and run, is consistent with that. This is not legal advice; read the LICENSE file before reusing substantial portions. On maintenance, the material supports a limited picture. There is an active contribution path through issues and pull requests, a named maintainer organization, and a last push date, but no releases and no stated review cadence. The cost of following the guide is therefore not upgrade work in the dependency sense. It is the reading time plus the verification time: for any pattern you adopt, you are checking it against the current behaviour of whichever runtime you use, because the guide will not do that for you. Budget for that. A guide with no releases is a guide whose accuracy you confirm yourself.
Editorial conclusion
Adopt this guide if you are building or evaluating an agent runtime and want a structured reading list that separates the harness layer from the framework layer. Do not adopt it if you need an installable dependency, a stable API surface, or versioned docs tied to a specific release. Before relying on any article, open the linked file under guide/ on the main branch and check the last commit date, because the repository carries no releases and the content tracks a field that changes monthly.
Community notes