harness-engineering: The Repo Behind OpenAI's Million-Line Codex Experiment Has 21 Stars

Ryan Lopopolo published the field guide to the practice that shipped a million lines of code with zero human keystrokes. It is designed to be read by your agent, not by you, and the throughput numbers behind it come with conditions nobody is repeating.

The lopopolo/harness-engineering repository went public over the weekend of July 18, tagged v1.0.0, and climbed to third on the Trendshift daily board. Open the GitHub page and the counters read 21 stars, 0 forks, 0 watchers, 2 commits. GitHub labels it 100% Python, which is technically true and completely misleading, because the only Python in it is one helper script that fetches an OpenAI blog post for agents that get blocked by the canonical page.

There is almost no code in this repository. It is docs/, playbooks/, evals/, sources/, and an AGENTS.md whose stated job is to route a task to the relevant arguments, cases, and proof. The README's instruction is not "read this." It is: point a coding agent at this repository alongside the system it should improve.

That is a strange artifact and I think it is the interesting part. Someone packaged a body of engineering judgment specifically so that a machine would consume it, and the practice it documents is the one that produced roughly a million lines of shipped code without a human typing any of it.

The claim underneath is not "agents can code now"

Lopopolo is the author of OpenAI's February 11 engineering post describing a five-month internal experiment: an internal beta product built with zero manually written lines. Every line of application logic, tests, CI configuration, documentation, observability, and internal tooling was written by Codex. Roughly 1,500 pull requests merged. It started with three engineers driving Codex at an average of 3.5 merged PRs per engineer per day, and the post reports throughput rising as the team grew to seven.

The interesting finding in that post is not the volume. It is what the engineers spent their time on once they were forbidden from writing code. Early progress was slower than expected, and the post is specific about why: not because Codex was incapable, but because the environment was underspecified. When something failed, the fix was almost never "try harder." The question the team asked instead was what capability is missing, and how do we make it both legible and enforceable for the agent.

That reframing is the whole practice. The discipline moved out of the code and into the scaffolding around it. Lopopolo's repository is an attempt to make that scaffolding transferable, and its core thesis has a name in the docs: make the repository teach the agent.

The mechanics worth stealing

AGENTS.md is a table of contents, not an encyclopedia. The team tried the one-big-file approach and the post names four specific ways it failed. Context is scarce, so a giant instruction file crowds out the task and the actual code. Too much guidance becomes non-guidance, because when everything is important the agent pattern-matches locally instead of navigating on purpose. It rots instantly into a graveyard of stale rules nobody maintains. And a single blob resists mechanical checking, so drift is guaranteed. Their replacement is roughly 100 lines of map.

The docs/ tree is the system of record. Design docs with an index and verification status, a core-beliefs file defining agent-first operating principles, execution plans split into active and completed with a tech-debt tracker, generated schema docs, product specs, and reference files for third-party tools in llms.txt form. All versioned next to the code. The point is progressive disclosure: the agent starts at a small stable entry point and learns where to look next.

Staleness is enforced by machines. Dedicated linters and CI jobs validate that the knowledge base is current, cross-linked, and structured correctly. A recurring doc-gardening agent scans for documentation that no longer matches real code behavior and opens fix-up pull requests. Documentation that only humans maintain will rot; documentation with a CI job attached has a chance.

Architecture is enforced, taste is not micromanaged. Each business domain is divided into a fixed layer set (Types, Config, Repo, Service, Runtime, UI) with strictly validated dependency directions, and cross-cutting concerns like auth and telemetry enter through a single explicit Providers interface. Anything else is disallowed mechanically, through custom linters that Codex wrote. The post is blunt that this is the kind of architecture you would normally postpone until you had hundreds of engineers, and that with agents it becomes an early prerequisite.

The single best mechanic in the whole post is one sentence about error messages. Because the lints are custom, they write the error messages to inject remediation instructions into agent context. Think about what that means. A lint failure stops being a complaint and becomes a delivery channel. The agent hits the wall and the wall tells it how to get over. Your review comment, written once, now fires on every line of code forever without you present.

What the agent cannot see does not exist. The architectural decision aligned in a Slack thread is invisible to the agent in exactly the way it is invisible to a new hire who joined three months later. Repository-local versioned artifacts are all it can read. This is why the team kept pushing more context into the repo over time rather than into a wiki.

Throughput inverts the merge philosophy. Minimal blocking merge gates, short-lived pull requests, test flakes handled with a follow-up run rather than an indefinite block. Their reasoning: when agent throughput far exceeds human attention, corrections are cheap and waiting is expensive. And the team used to spend every Friday, 20% of the week, cleaning up AI slop by hand. That did not scale, so they encoded "golden principles" into the repository and run background cleanup tasks that open targeted refactoring PRs on a cadence.

Put this into practice this week

You do not need a greenfield repo or a zero-human-code mandate to get value here. Four steps, in order of friction.

Cut your AGENTS.md or CLAUDE.md down to a map. If it is over 150 lines, it is an encyclopedia and your agent is already ignoring parts of it. Move the detail into docs/ and leave pointers. You will feel like you are deleting important instructions. Check whether the agent's behavior actually degrades before you put them back.

Pick your single most-repeated review comment and turn it into one lint. Not a rule in a markdown file. An actual check that fails, with an error message written for a reader who will act on it. Say what is wrong, why the boundary exists, and what the correct shape looks like. One lint, this week, is worth more than a rewritten instruction file.

Check your plans into the repo. Whatever you are currently pasting into a chat window as a plan, put it in docs/exec-plans/active/ instead and point the agent at the path. Move it to completed/ when it lands. This is nearly free and it is the fastest way to stop re-explaining context every session.

Add one staleness check. Even a CI job that fails when a doc references a file path that no longer exists will catch a surprising amount of drift.

And if you want to try the repository as designed, point your agent at it alongside your own codebase and ask it to critique your repository structure against the field guide. That is the use case it was built for, and it is a cheap experiment.

The conditions nobody is repeating

The practices generalize. The numbers do not, and the sourcing has real gaps.

The repository is two commits old and single-author. Twenty-one real stars against a top-three trending position tells you that board rank is momentum from mentions, not adoption. Nobody has forked it. Nobody is watching it. The v1.0.0 tag is a day old. Treat it as a good first draft by a credible author, which is what the README more or less calls it.

Its citation base leans on the author's own posts. The README's supporting links include several X posts by Lopopolo, including the "point their agents at my writing and improve the output 100x" quote it opens with. That is an assertion, not a measurement, and the repository ships no eval demonstrating the 100x. The evals/ directory exists; its contents are worth checking before you take the framing at face value.

The licensing has a seam. Repository-authored material is CC BY 4.0. GitHub also reports an unknown license in COPYING.md covering rights in the source material, since the anthology quotes work it does not own. If you plan to redistribute any of it, read that file first.

The OpenAI numbers came from conditions you almost certainly do not have. Greenfield repository, first commit into an empty git repo in late August 2025. No pre-existing human-written code to anchor anything. A team whose primary job was building the harness, not shipping features against a deadline someone else set. An internal beta with internal daily users and external alpha testers, which is a real product but not a system with regulatory exposure or a decade of accumulated constraints. The 3.5 PRs per engineer per day is throughput on that repo, not a forecast for yours.

OpenAI says so itself. On the end-to-end autonomy milestone, the post states plainly that the behavior depends heavily on the specific structure and tooling of that repository and should not be assumed to generalize without similar investment. On the merge philosophy, it says outright that minimal blocking gates would be irresponsible in a low-throughput environment. Both caveats get dropped from most summaries, and both are the difference between adopting a practice and cargo-culting one.

And an agent context bundle is an instruction channel. Pointing your agent at a third-party repository of markdown means piping someone else's prose into the surface your agent treats as guidance. That is the same shape as the skills supply-chain problem the industry has spent this month arguing about. This particular author is credible and the content is prose rather than executable hooks, so the risk here is low. The habit is what generalizes badly. Read what you point your agent at.

What to take from it

The reason this repository is worth twenty minutes is not that it will make your agent 100x better. It is that it names, with specifics, where the work went when the work stopped being typing.

Judgment that lives in your head does not survive contact with an agent. Judgment that lives in a Slack thread does not either. Judgment encoded as a lint with a remediation message in the error string runs on every change, forever, without you in the room. That is the compounding asset, and it is the one thing in this whole practice that survives switching models, switching agents, and switching vendors.

Start with one lint. See if the error message changes what the agent does next.

Sources: lopopolo/harness-engineering on GitHub; OpenAI engineering post, February 11, 2026; Trendshift repository page.