ReCode: Recursive Code Generation as a Unified Plan-and-Action Agent Loop

The Problem ReCode Attacks: Plan and Action Live in Separate Representations

Most LLM agent designs keep planning and acting apart. A planner emits a step, an executor runs it, and the observation comes back to the planner. The granularity of that step is fixed by the prompt: either the agent commits to a coarse strategy it cannot revise mid-flight, or it commits to a single tool call with no room for strategy. ReCode's stated goal is universal granularity control, meaning the same representation can hold a strategic sketch and a concrete action, and the agent can move between the two levels as observations arrive. The intended audience is narrow. This is the reference implementation used in the paper, together with environment wrappers and experiment tooling. It is written for people reproducing or extending that research, not for teams looking for an agent framework to drop into an application. The README points readers to the arXiv paper 2510.23564 for the argument, and to an email address for reproduction difficulties, which tells you where the support boundary sits.

Tree-Structured Code as the Unit of Work

The mechanism is a tree of partial programs. Each node captures one sub-task and records its execution trace. A node starts life as a placeholder function. The LLM expands that placeholder into more specific calls or smaller subroutines, using environment-specific prompts and few-shot examples. Expansion is recursive: a subroutine can itself contain placeholders that get expanded later. The important consequence is that the tree is not built in advance. Each node is executed immediately, and the fresh observation decides whether to expand further, retry, or finish. That is the difference from a static planner that produces a full decomposition up front. Here the decomposition is a side effect of execution, and the depth of the tree is a runtime decision rather than a prompt-time one. The README frames this as a divide-and-conquer strategy, and the four numbered points in the Core Idea section are the whole specification available without reading the paper.

The Constrained Executor Is the Real Safety Boundary

Generated code has to run somewhere. ReCode uses a shared executor state: a constrained Python executor that maintains environment variables, validates code blocks, and exposes the toolset available to the agent. The word constrained is doing a lot of work here, and the README does not enumerate the constraints. What it does say is that the executor validates code blocks before running them and that the toolset is exposed through it, so the agent's generated Python is not arbitrary Python with full process access. This is the component to read first in utils/, because it determines what a malformed expansion can actually do. If you are evaluating ReCode for anything beyond benchmark reproduction, the executor's validation rules are the thing that decides whether the approach is usable, and the README alone is not enough to answer that.

Getting It Running: Three Environments, One CLI

The Python version requirement is 3.10 or newer. The README explicitly warns that it has not been confirmed whether the three benchmark environments conflict in a single conda environment, and suggests configuring them separately. That is a real cost: three environments, three dependency sets, one agent. The setup starts with a conda environment, then per-environment work. For ALFWorld you follow the upstream ALFWorld instructions and either export ALFWORLD_DATA or edit envs/alfworld/base_config.yaml to point at local paths. For WebShop the repo borrows a setup script from ETO: cd envs/webshop, pip install -e ., conda install -y -c conda-forge openjdk=11, install the en_core_web_lg spaCy model wheel, then bash setup.sh to fetch the goal set and pre-built search index. ScienceWorld defers to its own repository. After that, pip install -r requirements.txt, which the README annotates with a note that it may not be complete. LLM access is configured through configs/profiles.yaml, with configs/profiles_example.yaml as a template you copy. A profile carries api_key, base_url, model, temperature, and optionally max_tokens and track_costs. Cost tracking reads configs/prices.json, and setting track_costs: false disables it. If you omit the file entirely, the default profile falls back to OPENAI_API_KEY in the environment. The canonical run command is python run.py -a recode -e alfworld -n 1 --split test --profile default, with alfworld swappable for webshop or sciworld once their assets exist. Logs land in logs/<run_id>/ and a condensed summary prints to the console. Note the README's own Quick Start block ends with a stray 'p' where the command was truncated, so trust run.py's argument names rather than that fragment.

What the Reported Numbers Do and Do Not Tell You

The README reports an average score of 60.8 across three environments, described as surpassing the best baseline by 10.5, a relative 20.9 percent, against ReAct, CodeAct, AdaPlanner and ADaPT. It also states a perfect 100 score in ALFWorld under claude-4-sonnet, qualified as being from the authors' own tests. Separately, supervised fine-tuning on Qwen2.5-7B-Instruct is reported at 70.4 percent average for ReCode+SFT, against 67.6 for ReAct+SFT and 55.8 for CodeAct+SFT. These are the authors' figures, not independently reproduced here, and the repo has no releases to pin them to. The more interesting claim is the SFT comparison, because it is about data efficiency rather than peak score: if the gap holds, ReCode traces are better training material per example. Treat that as a hypothesis to reproduce, not a settled result. The README gives no per-environment breakdown in text, only figures.

Where ReCode Is the Wrong Tool

The failure modes visible from the repository are structural, not incidental. First, there is no packaging and no releases. You get a main branch and a run.py entry point, which means no version to pin and no upgrade path other than tracking commits. Second, the dependency situation is acknowledged as uncertain: the README says it has not been confirmed whether the three environments conflict, recommends three separate conda environments, and annotates requirements.txt as possibly incomplete. Third, recursive expansion multiplies LLM calls. Every placeholder that gets expanded is another generation, and the dynamic loop means the number of generations depends on the trajectory rather than the task count. That is fine for benchmark runs with cost tracking enabled and a prices.json file; it is a poor fit for latency-sensitive serving. Fourth, the whole approach assumes the target environment has a Python toolset the executor can expose. If your environment is a set of HTTP APIs with no local execution, the recursive code generation premise has nothing to recurse into. Finally, the README gives no API stability statement, so anything importing agents/recode/ directly should expect breakage.

ReAct and CodeAct as the Baseline Contrast

The README positions ReCode against ReAct and CodeAct, and the difference is worth stating precisely. ReAct interleaves reasoning text with single actions, so the plan is prose and the action is one step. CodeAct makes the action a code block, which raises the expressiveness of a single step but keeps plan and action in sequence. ReCode's claim is that the placeholder function collapses the two: a plan is a function whose body is not yet written, and writing the body is the action. That is why the tree can be expanded lazily and why the same node type can hold strategy or a primitive call. The trade-off is that you now depend on the model generating syntactically valid, semantically appropriate Python at every expansion, and on the executor to catch the cases where it does not. ReAct degrades into a bad sentence; ReCode degrades into a failed code block. Which failure is cheaper depends on whether your executor validates before execution, which the README says it does.

Maintenance, Licence and What to Check First

The repository is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is the licence text's effect, not legal advice; check it against your own obligations. Maintenance signals are thin. There are no retrieved releases, the last push is 2026-04-21, and the README routes support to a personal email address rather than an issue tracker process. For a research artifact that is normal, but it means you own your fork. Upgrading means diffing main, and the config surface you would need to re-verify after any diff is small and enumerable: configs/profiles.yaml for credentials and model settings, configs/prices.json for cost accounting, and envs/alfworld/base_config.yaml for dataset paths. Start by confirming a single ALFWorld instance runs end to end, since that is the environment the README claims a perfect score in and therefore the one most likely to be in working order.

Editorial conclusion

Adopt ReCode if you are reproducing the paper or studying recursive plan decomposition in a controlled executor, and you can afford three separate conda environments for the three benchmark wrappers. Do not adopt it as a production agent runtime: there are no releases, no packaging, and the README itself flags that requirements.txt may be incomplete. Before anything else, verify that configs/profiles.yaml resolves to a working credential and that run.py -a recode -e alfworld -n 1 --split test --profile default completes on your machine.

Official sources

1. FoundationAgents/ReCode on GitHub
2. Issues
3. License: MIT
4. README