neal is a CLI I wrote while trying to use an LLM coding agent (in this case, Codex GPT-5.4) to work autonomously on a migration of our large frontend codebase. A few things came up during that project that guided the development of neal: 1. Telling an agent to "keep working unless blocked" doesn't actually work over long stretches of time. 2. Large projects should be broken up into smaller chunks of work. 3. The coding agent should start each chunk of work with a fresh context to prevent context rot. 4. The coding agent benefits from having a different agent doing adversarial reviews along the way. What I ended up with is an orchestrator that - lets you configure planner, coder, and reviewer roles. I started with Codex and Claude using their SDKs but later added OpenRouter as well as a compatibility mode for verifying that a model can handle the orchestration. Currently there are 44 compatible OpenRouter models. - runs a plan that you provide through a planner / reviewer loop which splits the work into reasonable-sized chunks and formats the plan document so that it can be executed by neal. - runs each chunk of work through a coder / read-only reviewer loop. Once both agents are satisfied, neal moves on to the next chunk. Once everything is complete there is a final pass through the coder / reviewer loop to ensure the implementation satisfies the entire plan. - resets the coder's context with each chunk of work to prevent context drift, leaving the reviewer's context long-running. The migration landed (549 commits, over 3000 files added/modified). I also ran 100 benchmark cases (from SWE-bench Pro) that Codex failed to solve on its own through neal and observed 8 solved when using neal with Codex in both (coder and reviewer) roles and 15 solved when using Claude as the reviewer. I had hoped for a more exciting benchmark outcome but this at least demonstrated neal's value, especially putting a different model in the reviewer role. neal is an npm package installed via I have a more detailed writeup of neal's capabilities and how it came to be on my blog: https://navels.dev/blog/neal/ With how fast model capabilities are progressing I'm not expecting this tool to be very useful for too much longer, but I'm still using it as my daily driver, with Claude Fable as the planner/coder and Codex Sol as the reviewer. If you try neal I'd love to hear your feedback, especially if you have a use case that doesn't quite work or you want additional models available. |