---
title: "codex-handoff v0.4 caps Codex fix loops at 2 rounds"
id: "story-78"
canonical_url: "https://emergent.fm/stories/78"
markdown_url: "https://emergent.fm/stories/78/article.md"
published_at: "2026-11-20T18:17:11.125Z"
modified_at: "2026-11-20T18:21:29.719Z"
topic: "agent_skills"
trust_label: "Reported"
publisher: "Emergent.FM"
---

# codex-handoff v0.4 caps Codex fix loops at 2 rounds

> Codex runs offline tests in its sandbox, while the commander agent runs builds and browser checks locally.

## Key points

- On 20 November 2026, codex-handoff v0.4 lowered its automated fix loop cap from 3 rounds to 2 rounds and split verification between Codex and the commander agent, according to the repository README.
- The MIT-licensed shell skill requires bash and a logged-in OpenAI Codex CLI backed by a ChatGPT subscription or an API key, the README states.
- The workflow runs implementation in a workspace-write sandbox and forces read-only mode with --ignore-user-config during reviews so no MCP servers or plugins load, according to the repository documentation.

On 20 November 2026, the maintainers of codex-handoff released v0.4 to stop sandboxed Codex runs from repeatedly failing on checks that require local environment access, according to the commit message and README. Under the updated handoff template, Codex runs linting, type checks, and relevant offline unit tests inside its sandbox. The commander agent, such as Claude Code or Cursor, runs builds, HTTP or browser checks, port tests, and external tools like helm once on the local machine. When remaining defects only trigger in extreme scenarios, the skill instructs the commander to ask the user earlier whether to document a known boundary or change the design.

## How the handoff workflow runs

A builder starts by asking a shell-capable commander agent to hand a scoped task from the project plan to Codex, according to the README. The unified shell script codex-task.sh handles the lifecycle through check, new, list, run, resume, and review commands. Running new generates a handoff file outside the repository under ~/.local/state/codex-handoff/<repo>/, a path configurable via CODEX_HANDOFF_HOME, so execution logs stay out of Git. Each run appends the Codex report to the handoff file and saves the Codex session ID in an adjacent .thread file. If the commander runs a separate review in the same directory, resume still continues the original task thread instead of picking the last session.

## Requirements and safety boundaries

The repository is written entirely in Shell under the MIT license and depends only on bash and the codex exec CLI, avoiding proprietary agent plugins, the README states. Builders can install it globally with npx skills add kuzicode/codex-handoff or copy the skill folder directly into an agent directory. For safety, codex-task.sh never passes --dangerously-* flags and leaves model selection to the user configuration. The documentation forbids rewriting tests to work around sandbox limits; checks involving .git, open ports, or network access must be reported as unverified items for the commander to run locally.

## Sources

- [Latest commit](<https://github.com/kuzicode/codex-handoff>) (github.com/kuzicode, 2026-11-20, release)

Canonical page: <https://emergent.fm/stories/78>
