neal Runs Claude and Codex Together

neal is an MIT-licensed TypeScript CLI project by GitHub user navels that runs a local planner, coder, and reviewer loop inside a repository. It deals with a very familiar agent problem: one long autonomous coding run slowly loses the plot on a large migration. The takeaway is simple: split the work into reviewable scopes, reset context between scopes, and make a different model review the changes before continuing.

neal is a plan-driven multi-agent coding loop for local software work. The useful angle for codex cli github workflows is not that it adds another chatbot; it shows how OpenAI Codex, OpenAI’s coding agent surface, and Claude, Anthropic’s assistant family, can be assigned different jobs in the same repo.

Understand what neal actually does

neal starts with a human-written plan. Its planner and reviewer turn that plan into a human-reviewable execution shape, with smaller scopes and high-level implementation detail grounded in the current repository.

Then the loop runs each scope with the configured coder and reviewer roles. The README’s core idea is deliberately adversarial: the coder and reviewer can use different vendors and models, so one model is not simply grading its own work.

The other important design choice is fresh context. Each scope starts the coder from a clean context, which is meant to reduce context rot during long work. That matters in exactly the kind of frontend migration that inspired the project: many files, repeated patterns, and enough edge cases that a single giant prompt becomes mush.

The trap is treating neal as magic autonomy. It is closer to a disciplined workbench. You still need a plan, a repo that can verify changes, and a human willing to read the execution artifacts under .neal/ when something gets interrupted or looks odd.

See why developers cared

The project landed because it names a pain many Codex CLI users have already felt. “Keep working unless blocked” sounds reasonable, but it is a weak control loop over several hours of code edits.

The better primitive is scoped progress. A scope might be “migrate all Button usages from variant="danger" to tone="critical" in packages/admin,” not “migrate the design system.” That gives the coder a finite target and gives the reviewer a real diff to inspect.

There is also a subtle review lesson here. A second model can catch mistakes the first model confidently walked past, especially when the second model is not sharing the exact same context trail. This does not make the review “correct,” but it makes it less self-referential.

The objection is fair: multi-agent loops can become ceremony. If your change is a three-line bug fix, adding planner, coder, reviewer, and final review passes may be slower than using Codex directly. neal is interesting when the work is too large for one comfortable agent pass but still concrete enough to express as a migration plan.

Try it on one Codex-shaped migration

The safest experiment is a narrow migration in a repo that already has tests. This is where the CLI workflow topic becomes practical: keep Codex close to the repository, keep instructions durable, and verify through commands instead of vibes.

For a codex cli github-style experiment, pick one package and one mechanical change. For example, migrate a deprecated React prop in apps/dashboard, or replace one wrapper API in packages/ui. Do not start with “modernize the frontend.” That is how context rot wins.

Before running any agent loop, put the repo rules where tools can find them. A small AGENTS.md is enough:

# AGENTS.md

## Scope rules
- Work only inside apps/dashboard and packages/ui unless the plan says otherwise.
- Keep public component APIs backward-compatible unless a scope explicitly removes one.
- Do not update snapshots without explaining the behavior change.

## Verification
- Run pnpm lint after each accepted scope.
- Run pnpm test --filter dashboard for UI-facing changes.
- Include any failing command and the observed error in the handoff.

That file is not a neal feature by itself. It is a Codex-friendly boundary: durable, repo-local, and reviewable. If neal’s loop produces a scope that violates it, the reviewer has something concrete to reject.

If you use Model Context Protocol servers in the same workflow, keep the first pass boring. Read-only GitHub and issue context is safer than write-capable Slack, Jira, or database access. MCP is powerful glue, but a migration loop should not need broad external permissions on day one.

Review the run without replaying chat

The nice thing about neal’s shape is that it creates artifacts. The .neal/ directory records run state so interrupted work can resume. That is more useful than scrolling through one huge terminal transcript and trying to reconstruct why a file changed.

A good review reads the plan, the scope, the diff, and the verification output in that order. If the diff is hard to explain at the scope level, the scope was probably too large. If the tests are missing, the reviewer should treat that as an unresolved task, not a minor note.

This is where neal sits near other agent-watch workflows, including experiments like tmux-agent-switcher Watches Coding Agents. The common thread is not “more agents.” It is making long-running agent work observable before it reaches your main branch.

The trap is accepting the final review because the loop completed. Completion is not correctness. The final pass should answer one boring question: did the total change still match the original plan after all scoped edits landed?

Try it safely checklist

Use this checklist for a first neal experiment, not a permanent process.

A good first run is intentionally small. Let neal migrate one package, inspect the artifacts, and only then decide whether the planner/coder/reviewer split helped.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

- [ ] Name the Codex artifact first: an AGENTS.md instruction, a Codex CLI verification loop, an MCP boundary note, or a skills handoff.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• What should teams know about codex cli github?

  Start by writing down one visible team rule for Codex, not a loose preference. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Codex artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a AGENTS.md instruction, MCP note, or verification checklist. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Codex teams deciding which AGENTS.md instruction, CLI workflow, MCP boundary, or verification loop to standardize next around “neal Runs Claude and Codex Together.”
• Best first artifact: turn the named fix into an AGENTS.md rule, verification checklist, MCP note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Codex CLI review loop, shell boundary, and evidence trail; keep the path that leaves the shortest auditable trail.

Further reading

• neal — source
• OpenAI Developers — Codex CLI
• GitHub — openai/codex
• OpenAI developers: codex quickstart

Next move

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.