Foam-Agent automates OpenFOAM simulations from a natural language prompt or an existing case. Its agents plan the case, prepare meshes and input files, run locally or through Slurm, repair errors, and optionally visualize results.
- OpenFOAM targets: Foundation v10 by default, with a separate native ESI/OpenCFD v2006 target.
- Tutorial retrieval: FAISS indices provide references from the selected target's tutorials.
- Model choice: OpenAI, Codex subscription, Anthropic, Bedrock, Ollama, and DeepSeek backends.
- MCP integration: Tools for Claude Code, Cursor, and other MCP clients.
Docker bundles Foundation OpenFOAM v10, Python dependencies, tutorial indices, and the default Qwen 0.6B embedding weights. No host Conda, OpenFOAM, or GPU is needed. Configure an API-key provider or a Codex subscription using the authentication guide. For Ollama, follow the local setup: it requires optional Python packages and a running Ollama service, which the default images do not include.
| Your environment | Installation |
|---|---|
| A host with Docker | Use the Docker steps below |
| An existing container or OpenFOAM installation | Local Python installation |
| Native ESI/OpenCFD v2006 | Build its matching image |
Build the current source on Linux amd64 (or an amd64 Docker VM):
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/csml-rpi/Foam-Agent.git
cd Foam-Agent
git lfs install
git lfs pull --include="database/foundation-v10/raw/*,database/foundation-v10/faiss/Qwen_Qwen3-Embedding-0.6B/**,examples/tandem-wing/*.msh"
docker build --platform linux/amd64 -f docker/Dockerfile -t foamagent:local .
cp .env.example .envEdit .env with your provider, model and API key. Then check the installation
and run the bundled example, keeping results on the host:
mkdir -p output
docker run --rm --env-file .env foamagent:local \
python scripts/doctor.py --check-embedding --check-llm
docker run --rm --env-file .env \
-v "$PWD/output:/home/openfoam/Foam-Agent/output" \
foamagent:local bash examples/quickstart/run.shThe diagnostic checks LLM access with a small request; the example uses the existing
user_requirement.txt. Files and logs are saved to output/quickstart/.
Use a fresh output directory for another run. See authentication
for a Codex subscription or another provider.
Locally built images run their bundled code and assets without startup updates. See Docker builds for native targets and older image compatibility.
To use your own prompt, mount its directory read-only and pass the container path:
docker run --rm --env-file .env \
-v "$PWD/inputs:/inputs:ro" \
-v "$PWD/output:/home/openfoam/Foam-Agent/output" \
foamagent:local python foambench_main.py \
--prompt_path /inputs/requirements.txt --output ./output/my-caseAn existing directory or ZIP is also supported with
--case_path. Foam-Agent keeps an original/ copy and runs in work/.
| Environment variable | Purpose | Default |
|---|---|---|
FOAMAGENT_MODEL_PROVIDER |
LLM backend | openai-codex |
FOAMAGENT_MODEL_VERSION |
Model identifier for that backend | gpt-5.3-codex |
FOAMAGENT_EMBEDDING_PROVIDER |
Tutorial embedding backend | huggingface |
FOAMAGENT_EMBEDDING_MODEL |
Model identity matching the FAISS indices | Qwen/Qwen3-Embedding-0.6B |
FOAMAGENT_EMBEDDING_MODEL_PATH |
Optional local copy of that Hugging Face model | Unset |
FOAMAGENT_OPENFOAM_TARGET |
Native target: foundation-v10 or esi-v2006 |
Unset; Foundation v10 |
The default LLM uses a Codex OAuth cache. An API key requires selecting its provider and model explicitly, as in Quick Start. Docker builds bundle the default embedding weights. Local Python installations may download them on first use; prebuilt tutorial indices come through Git LFS and must match the embedding model. See installation checks and offline setup.
Settings live in src/config.py; see configuration for credentials, the legacy ESI translation switch, generation modes, and retry limits. Native ESI v2006 requires its matching runtime/image and corpus.
After local installation, register the server with Claude Code:
claude mcp add foamagent -- foamagent-mcpThe repository also includes the /foam Claude Code skill. See the MCP guide for other clients, HTTP/Docker setup, tool arguments, and workflow limits.
- Usage guide: configuration, existing cases, custom meshes, native targets, Slurm, and Docker builds.
- MCP guide: client setup and available tools.
- DeepWiki: project introduction and interactive questions.
| Directory | Contents |
|---|---|
src/ |
Workflow, services, model clients, and MCP server |
database/ |
Target-specific tutorial corpora, FAISS indices, and builders |
examples/ |
Sample inputs, including the tandem-wing mesh and prompt |
docs/ |
User guides and illustrations |
scripts/ |
Corpus checks and translation verification tools |
tests/ |
Automated regression tests |
docker/ |
Runtime images and entrypoints |
These are the project's recorded FoamBench results, not guarantees for the current working tree, native ESI v2006, or arbitrary imported cases.
| Framework | Model | Basic | Advanced |
|---|---|---|---|
| FoamAgent 2.0.0 (10 loops) | Opus 4.6 | 85.45% | 100% |
| FoamAgent 2.0.0 (25 loops) | Opus 4.6 | 100% | 100% |
| FoamAgent 2.0.0 (25 loops) | Sonnet 4.6 | 87.88% | 75.00% |
| FoamAgent 2.0.0 (25 loops) | Haiku 4.6 | 54.55% | 37.50% |
| FoamAgent 2.0.0 (25 loops) | gpt-5.4 | 45.45% | 75.00% |
| FoamAgent 2.0.0 (25 loops) | gpt-5.3-codex | 54.55% | 62.50% |
The highest reported scores in this table use Anthropic Claude Opus 4.6; model selection remains configurable.
Chinese-speaking users can add ZDSJTUCFD on WeChat to request an invitation to the Foam-Agent community.
If you use Foam-Agent in your research, please cite our paper:
@article{yue2025foam,
title = {Foam-Agent: A large language model-based multi-agent framework for automating computational fluid dynamics workflows},
journal = {Computer Methods in Applied Mechanics and Engineering},
volume = {461},
pages = {119271},
year = {2026},
issn = {0045-7825},
author = {Ling Yue and Nithin Somasekharan and Tingwen Zhang and Yadi Cao and Zhangze Chen and Shimin Di and Shaowu Pan}
}