How to build a Codex loop harness

A Codex loop harness is the control layer around repeated Codex CLI work. It supplies the task, invokes a worker, runs a verifier before and after each iteration, records what changed, and stops on a defined outcome. The harness does not make the coding model infallible. It makes the work bounded, observable, and easier to review.

LoopLatch generates the bootstrap prompt for that control layer. You download the prompt, review it, and run it with Codex CLI in the intended Git repository. Codex can then inspect the repository's AGENTS.md, architecture decisions, package manager, and validation commands before creating a repository-specific local harness. No repository content needs to be uploaded to LoopLatch.

The quality of the loop depends on three inputs that have different jobs. The task describes the change and its boundaries. The verifier provides an external, repeatable success signal. Stop conditions limit the amount of time and repetition the worker receives when the verifier remains red.

Keep the task narrow enough that one repository area and one coherent proof can describe it. A request such as “improve the app” leaves the worker to invent scope. A request such as “fix the empty-state regression in the review panel without changing populated results” identifies the behavior, boundary, and non-goal.

A verifier should be independent of the worker's own explanation. “Codex says the feature is finished” is not proof. A focused test, type check, lint rule, build, or repository-owned validation script can provide a machine-observable exit status. Run the narrowest check that fully proves the requested behavior, then include broader repository gates when the local contribution rules require them.

Prefer stable commands that produce the same result from the same repository state. Nondeterministic network calls, time-sensitive snapshots, and flaky end-to-end suites make repeated-failure detection less useful. If the only available proof is broad or slow, set the total timeout and iteration budget with that cost in mind.

LoopLatch stops before repository execution. Prompt and ZIP generation happen in the browser. The downloaded bootstrap prompt is the boundary: you can inspect the exact task, verifier, permissions, limits, and requested files before Codex sees the repository.

After saving the prompt at the repository root, review it and run the documented Codex CLI command. The local bootstrap operation should stop if intended harness files already exist instead of overwriting or merging them. Review the generated shell script, task file, configuration, result schema, and README before starting the loop itself.

A verifier-first loop checks whether the repository is already complete before asking a worker to edit anything. If the verifier passes, the loop exits successfully without an unnecessary model turn. Otherwise, the harness creates the next worker prompt from the task and accumulated audit state, runs Codex with a structured result schema, and executes the verifier again.

The worker result can report changes, no changes, a blocker, or a request for one exact approval. It cannot declare success. The post-worker verifier determines that. The harness then records the result and stops or continues according to the configured budget and failure identity.

The five LoopLatch presets change guidance and examples, not the underlying safety contract. Test-Fix fits a reproducible failing suite. Feature Implementation fits explicit acceptance criteria. CI Autofix translates a reproducible CI failure into a minimal local repair. Review-Fix keeps a bounded set of feedback items tied to regression proof. Custom covers another narrow task that still has an external verifier.

A preset is a starting point, not permission to widen the task. If the request is still fuzzy, shape it into a verified specification before generating a loop. If the affected repository area is unclear, map callers and structural matches first. Optional Agent Skills can help with those preparation steps without changing the LoopLatch artifact contract.

Most weak loops fail before the first worker starts: the task is too broad, the verifier does not measure the requested behavior, or the budget is disconnected from verification cost. Other failures appear when a loop runs against an unreviewed dirty worktree, silently overwrites harness files, repeats the same failure, or treats a worker summary as proof.

Use a clean worktree by default, inspect collisions, and keep one total deadline. For risky actions, require an exact action and one-use interactive approval rather than a standing category permission. A bounded loop may still produce incorrect code, so repository review and validation remain mandatory.