neal: coordinating different models on complex coding projects<br>Aug 4, 2026<br>neal: coordinating different models on complex coding projects

The first version of neal was a plan file and this prompt:

Execute @plans/EMBER_MIGRATION.md. keep going. don't stop unless you are blocked.<br>I typed that into Codex during a large frontend framework upgrade at work. GPT-5.4 was the current model at the time. I wanted to hand it several months of tedious work, check in periodically, and otherwise let it keep moving. Each time the arrangement broke down, I added something. That eventually became neal, a local CLI that coordinates coding agents around a plan.

The migration

Our frontend codebase had been due for an upgrade from Ember.js v3 to v5 (ahem… v6) for a long time. This would impact virtually all of our code: thousands of files, significant syntax changes, and replacement of deprecated patterns. Most of the edits were repetitive, but not easily scriptable. Some shared components would have to be completely reworked. We estimated the manual work to be over 300 engineering hours. Even with our reasonably comprehensive test suite, the project carried significant risk.

With a lean engineering team, it seemed like an impossible task. Until coding agents came along. In mid-2025, I excitedly put Claude Sonnet 4 on the task, only to watch it play whack-a-mole endlessly with our test suite, fixing and causing the same bugs over and over. The amount of babysitting required at the time was too much to justify the mediocre results. The migration was shelved.

Earlier this year, we felt like it was time to try again. Codex and Claude models had improved significantly at planning, coding, and working autonomously. I hoped that with a detailed migration plan doc, one of the frontier coding agents could work through the migration incrementally on its own, with me checking in to review progress along the way.

Codex kept stopping

The migration plan had links to Ember upgrade resources, commands for running the test suite, and an instruction to work on 10 to 20 related files at a time. It also kept a list of files that still needed to be migrated, so Codex could pick up where it left off when interrupted.

For a while, the bare prompt worked surprisingly well. Codex could work on its own for long stretches. When I restarted it, the plan still showed what was finished, what came next, and which constraints applied to the remaining work.

The problem was keeping it going. Codex would finish a batch and stop for no apparent reason. I would ask, “Why did you stop iterating on the migration?” The reply was often, “I didn’t,” despite having been idle for hours.

Long sessions uncovered a second problem. Codex gradually drifted from the instructions it had followed earlier. I added “Re-read this migration plan before starting on the next batch of files” to the plan, but that wasn’t always enough. I found a name for this behavior: context rot. Over a long session, old instructions and decisions lose influence as the context grows or is compacted.

I tried to solve both problems inside Codex. I turned the prompt into a $work-autonomously skill with a Stop hook, textual markers to signify that a batch of files had been completed or a blocker encountered, and an instruction to reset the agent context via /new before each batch. The skill helped, but Codex still didn’t always remember to start a new context.

I asked Codex:

you don't always follow the instruction to start a new context with every chunk of work. how feasible would it be to build a node app to direct codex to do a chunk of work?<br>This was the precursor to neal: a node script using the Codex SDK to execute the migration in a loop.

A second model for review

Reviewing the incremental migration commits exposed another issue. Code quality was not always the greatest. I decided to incorporate a common workflow of mine: have Codex implement a thing, have Claude review it, and have Codex respond to Claude’s feedback. I would repeat that until both models agreed, then review the change myself.

I added this to the node script using the Claude SDK to review the latest commit. The script captured Claude’s feedback and sent it to Codex. At this point I decided to give my orchestrator a name: neal.

The name comes from anneal, the process of heating and cooling a material in controlled cycles until its internal stresses settle. I dropped the “an” and kept the process.

What neal does

neal is a local CLI that coordinates planner, coder, and reviewer roles around a plan document. You choose the provider and model for each role. These days I am using Anthropic’s Fable as the coder and OpenAI’s Sol as the reviewer.

neal run is the normal workflow. It starts by sending a rough plan through the planner and reviewer. They give it an execution shape, split larger work into scopes, and fill in the implementation approach, verification, and success conditions. They leave file-level discovery and...