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. One long autonomous coding run slowly loses the plot on a large migration. 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 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.

Don't treat 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.

Don't accept 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.

Further reading

• neal on GitHub
• Codex CLI docs
• Codex on GitHub

Next move

Start from CLI workflows.