Foam-Agent: a LangGraph pipeline that writes and runs OpenFOAM cases from one prompt
Foam-Agent: An end-to-end, composable multi-agent framework for automating CFD simulations in OpenFOAM. NeurIPS 2025 Machine Learning and the Physical Sciences Workshop.
At a glance
- What is it?
- Foam-Agent wraps OpenFOAM case setup, execution and error repair in a multi-agent loop with FAISS retrieval over tutorial cases. The README reports a 100 percent success rate on FoamBench with Claude Opus 4.6, and a 54.55 percent basic score with Haiku 4.6.
- Who is it for?
- Adopt Foam-Agent if your team already runs OpenFOAM v10, your cases resemble the tutorial corpus, and you are willing to pay for a strong model: the README's own table shows Haiku 4.6 at 54.55 percent basic and gpt-5.4 at 45.45 percent, so a cheap backend changes the outcome more than any flag.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The expertise barrier Foam-Agent is trying to remove
OpenFOAM case setup is a file-writing exercise spread across a directory tree: blockMeshDict, controlDict, fvSchemes, fvSolution, and one file per boundary patch under 0. The physics is not the hard part for an engineer who already knows what they want. The hard part is remembering which dictionary key takes a keyword versus a scalar, which scheme name is valid for the chosen solver, and why the run diverged at timestep 400. Foam-Agent targets that gap. The README describes it as automating the entire OpenFOAM-based CFD simulation workflow from a single natural language prompt, covering meshing, case setup, execution, error correction and post-processing. The intended user is someone who can write a prompt like the pitzdaily example in the README (RAS, PIMPLE, fixed inlet velocity of 10 m/s, zero gradient pressure, no-slip walls, timestep 0.0001, endTime 0.3, nu 1e-5) but who does not want to hand-assemble the dictionaries. It is not a solver, not a mesher, and not a replacement for understanding the case. It is a generator and a repair loop around tools you already have.
Architect, Input Writer, Runner, Reviewer: the loop and its 25 iterations
The README names four agents: Architect, Input Writer, Runner and Reviewer. They are wired together as a LangGraph pipeline, and the pipeline includes automatic error correction for up to 25 iterations. That number is the single most important design parameter in the project, and the README's own benchmark table shows why. FoamAgent 2.0.0 with Opus 4.6 scores 85.45 percent on basic tasks in 10 loops and 100 percent in 25 loops. The extra 15 iterations buy the last 14.55 points. Error correction here is not a nicety bolted onto generation; it is load-bearing. The generation side is retrieval-augmented: hierarchical FAISS indices are built from OpenFOAM tutorials, so the Input Writer retrieves context-specific material before writing configuration files. That is a sensible choice for a domain where most cases are variations on a small number of canonical setups, and it is also the source of the framework's main structural weakness, which I take up below. The Input Writer has two modes, set via input_writer_generation_mode in src/config.py. sequential_dependency generates files in order with cross-file context and is recommended for expensive runs on HPC or long simulations. parallel_no_context generates files in parallel without cross-file context and is recommended for fast local runs where retry is cheap. That is a real trade-off stated plainly, and it maps onto the cost model of the two situations.
Getting it running: Docker, the prompt file, and one command
The fastest path is the published image, which the README says ships OpenFOAM v10, Conda and all dependencies. You pass an API key, publish port 7860, and name the container:
docker run -it -e OPENAI_API_KEY=your-key-here -p 7860:7860 --name foamagent leoyue123/foamagent
Inside the container you edit user_requirement.txt, then run:
python foambench_main.py --output ./output --prompt_path ./user_requirement.txt
A pinned release is available as leoyue123/foamagent:v2.0.0. Configuration lives in src/config.py, and the README states every setting can be overridden by environment variable, which matters for Docker and CI. The relevant keys are FOAMAGENT_MODEL_PROVIDER (openai, openai-codex, anthropic, bedrock, ollama), FOAMAGENT_MODEL_VERSION, FOAMAGENT_EMBEDDING_PROVIDER (openai, huggingface, ollama) and FOAMAGENT_EMBEDDING_MODEL. The embedding default is huggingface with Qwen/Qwen3-Embedding-0.6B, which runs locally and needs no API key. For a custom mesh, pass --custom_mesh_path ./tandem_wing.msh; the README specifies ASCII 2.2 Gmsh files and asks you to describe the boundary conditions in the prompt. There is also an MCP server. A local install is pip install -e ., which adds the foamagent-mcp command, registered with claude mcp add foamagent -- foamagent-mcp. In Docker you start it with foamagent-mcp --transport http --host 0.0.0.0 --port 7860 and point an MCP client at http://localhost:7860/mcp. A Claude Code skill, /foam, is included.
The model is the success rate, and the README says so
The recommended-models table is the most useful page of documentation in the repository, and it is also the project's clearest limitation. With 25 loops, Opus 4.6 reaches 100 percent on both basic and advanced tasks. Sonnet 4.6 reaches 87.88 percent basic and 75.00 percent advanced. Haiku 4.6 reaches 54.55 percent basic and 37.50 percent advanced. gpt-5.4 reaches 45.45 percent basic and 75.00 percent advanced. gpt-5.3-codex reaches 54.55 percent basic and 62.50 percent advanced. Read that as a cost statement: the framework is not model-agnostic in any practical sense. Swapping to a cheaper backend does not degrade gracefully, it roughly halves the basic success rate. The README explicitly recommends Anthropic Claude Opus 4.6 for best results. There is a second axis of cost the table does not show: 25 repair iterations means up to 25 model calls per case, each carrying retrieved context. For a batch of 110 FoamBench tasks that is a large token bill, and the README gives no per-case token figure. Anyone budgeting this should measure it themselves rather than assume.
Where the retrieval assumption breaks
The FAISS indices are built from OpenFOAM tutorials, and hierarchical retrieval over tutorials is the mechanism that makes generated dictionaries plausible. This works when your case is a variation on a tutorial: pitzdaily, a channel, a tandem wing. It works less well when your geometry, your turbulence modelling choice, or your boundary condition set has no close neighbour in that corpus. The failure mode is not a crash. It is a case that runs, converges, and answers a slightly different question than the one you asked, because the retrieved context pulled the generation toward the nearest tutorial. The README's custom mesh path sharpens this: you supply a Gmsh .msh file and describe the boundary conditions in the prompt, so the mapping from mesh patches to OpenFOAM patch names and types is inferred from prose. Nothing in the supplied material describes a validation step that checks the generated boundary conditions against the actual mesh patches before the run. If you use --custom_mesh_path, that check is on you.
OpenFOAM forks, and what FOAMAGENT_OPENFOAM_FORK actually promises
Foam-Agent generates output following Foundation OpenFOAM v10 conventions by default. The README states that if FOAMAGENT_OPENFOAM_FORK=esi is set, generated input files are translated to ESI OpenFOAM (openfoam.com) naming and dictionary conventions on a best-effort basis. Best-effort is the operative phrase, and it is a meaningful caveat rather than boilerplate: the two distributions differ in dictionary names and conventions, and a translation that is nearly right produces a case that either fails to parse or, worse, parses into something subtly different. If your installation is ESI, set the variable and then diff the generated files against a case you know runs on your build. If you are on Foundation v10, the default path is the one the benchmark numbers were produced on, which is the configuration I would trust first.
What this replaces, and what it does not
The obvious alternative is writing the dictionaries yourself, or starting from an OpenFOAM tutorial case and editing it. That is slower per case and does not scale to a batch of a hundred parameter variations, but it produces a case you can explain line by line. A narrower alternative is the MCP tool surface: if you already work inside Claude Code, Cursor or Windsurf, you can expose Foam-Agent's functions as tools and drive individual steps rather than the whole pipeline. That keeps a human at the boundaries between meshing, generation and execution, which is where the silent-physics-change risk lives. The difference in approach is real. The full pipeline optimises for a single prompt producing a finished run. The MCP route optimises for a person staying in the loop. Which one you want depends on whether a wrong-but-converged answer is cheap or expensive for you. The README's own framing, one prompt does it all, tells you which side of that line the project is built for.
Licence, maintenance and the cost of keeping up
Foam-Agent is MIT-licensed, which is permissive and places few obligations on how you use or redistribute it; I am not a lawyer and this is not legal advice. Note that the licence covers Foam-Agent's own code, not OpenFOAM, which you obtain separately and which carries its own terms. On maintenance, the repository shows three releases between October 2025 and April 2026, with v2.0.0 adding MCP and what the release title calls safer model and auth options, and v2.1.0 following a month later. The last push recorded is August 2026. The upgrade cost that matters here is not the code. It is the model dependency: the benchmark table is tied to specific model versions, and those versions are controlled by an external vendor. A model deprecation or a behaviour change in a hosted endpoint can move your success rate without a single commit to Foam-Agent. Pin FOAMAGENT_MODEL_VERSION in your environment and re-run a known case after any change to it. That is the upgrade test this project actually requires.
Editorial conclusion
Adopt Foam-Agent if your team already runs OpenFOAM v10, your cases resemble the tutorial corpus, and you are willing to pay for a strong model: the README's own table shows Haiku 4.6 at 54.55 percent basic and gpt-5.4 at 45.45 percent, so a cheap backend changes the outcome more than any flag. Do not adopt it for production meshing of complex industrial geometry or for work that requires reproducible, auditable case construction, because the pipeline generates files rather than deriving them. Before committing, verify three things: that your OpenFOAM fork matches FOAMAGENT_OPENFOAM_FORK, that your prompt survives the 25-iteration repair loop without silently changing the physics, and that you can read the generated case files well enough to check them.
Community notes