An End-to-End Composable Multi-Agent Framework for Automating CFD Simulation in OpenFOAM

Foam-Agent automates the entire OpenFOAM-based CFD simulation workflow from a single natural language prompt. It manages meshing, case setup, execution, error correction, and post-processing — dramatically lowering the expertise barrier for Computational Fluid Dynamics. Evaluated on FoamBench with 110 simulation tasks, our framework achieves an 100% success rate with Claude Opus 4.6.

Visit deepwiki.com/csml-rpi/Foam-Agent for a comprehensive introduction and to ask questions interactively.

• End-to-End Automation: From meshing (including external Gmsh .msh files) to HPC job submission to ParaView/PyVista visualization — one prompt does it all.
• Multi-Agent Workflow: Architect, Input Writer, Runner, and Reviewer agents collaborate through a LangGraph pipeline with automatic error correction (up to 25 iterations).
• RAG-Enhanced Generation: Hierarchical FAISS indices built from OpenFOAM tutorials provide context-specific retrieval for accurate configuration file generation.
• Composable Service Architecture: Core functions are exposed as MCP tools, enabling integration with Claude Code, Cursor, and other agentic systems.

docker run -it \ -e OPENAI_API_KEY=your-key-here \ -p 7860:7860 \ --name foamagent \ leoyue123/foamagent

The container comes with OpenFOAM v10, Conda, and all dependencies pre-installed.

For a specific release: docker pull leoyue123/foamagent:v2.0.0

Edit user_requirement.txt inside the container:

do a Reynolds-Averaged Simulation (RAS) pitzdaily simulation. Use PIMPLE algorithm. The domain is a 2D millimeter-scale channel geometry. Boundary conditions specify a fixed velocity of 10m/s at the inlet (left), zero gradient pressure at the outlet (right), and no-slip conditions for walls. Use timestep of 0.0001 and output every 0.01. Finaltime is 0.3. use nu value of 1e-5. 

python foambench_main.py --output ./output --prompt_path ./user_requirement.txt

That's it. Foam-Agent will plan the case, generate all OpenFOAM files, run the simulation, and fix errors automatically.

All settings live in src/config.py with sensible defaults. Every setting can be overridden via environment variables — no need to edit files, especially useful for Docker and CI.

Example:

docker run -it \ -e FOAMAGENT_MODEL_PROVIDER=anthropic \ -e ANTHROPIC_API_KEY=your-key-here \ -e FOAMAGENT_MODEL_VERSION=claude-opus-4-6 \ -p 7860:7860 \ leoyue123/foamagent

Defaults to huggingface with Qwen/Qwen3-Embedding-0.6B (runs locally, no API key needed).

Set in src/config.py via input_writer_generation_mode:

We recommend Anthropic Claude Opus 4.6 for best results.

Foam-Agent supports external Gmsh .msh files (ASCII 2.2 format). Describe boundary conditions in your prompt and pass the mesh:

python foambench_main.py \ --output ./output \ --prompt_path ./user_req_tandem_wing.txt \ --custom_mesh_path ./tandem_wing.msh

To mount a mesh file from the host into Docker:

docker run -it \ -e OPENAI_API_KEY=your-key-here \ -v /path/to/my_mesh.msh:/home/openfoam/Foam-Agent/my_mesh.msh \ -p 7860:7860 \ leoyue123/foamagent

Foam-Agent exposes its full CFD workflow as an MCP server — the universal protocol supported by Claude Code, Cursor, Windsurf, and other AI-powered tools. It also ships with a Claude Code skill (/foam) for one-command simulation runs.

# 1. Install (adds the foamagent-mcp command) pip install -e . # 2. Register with your AI tool claude mcp add foamagent -- foamagent-mcp # Claude Code

For Cursor: open Settings > Features > MCP > Edit MCP Settings, and add:

{ "mcpServers": { "foamagent": { "command": "foamagent-mcp" } } }

For Windsurf / other MCP-compatible tools, use the same JSON config above.

If running in Docker, start the HTTP server and point your MCP client at it:

docker run -it \ -e OPENAI_API_KEY=your-key-here \ -p 7860:7860 \ leoyue123/foamagent \ foamagent-mcp --transport http --host 0.0.0.0 --port 7860

Then configure your MCP client:

{ "mcpServers": { "foamagent": { "url": "http://localhost:7860/mcp" } } }

If running Docker on a remote server, ensure port 7860 is reachable (e.g., via SSH port forwarding or -p 7860:7860).

For Claude Code users who clone this repo, a /foam skill is included in .claude/skills/foam.md. It orchestrates the MCP tools into a complete workflow:

/foam Simulate lid-driven cavity flow at Re=1000 

This triggers the full pipeline: plan -> generate files -> run -> review/fix loop -> visualize.

If you have a ChatGPT/Codex subscription, you can authenticate via OAuth instead of an API key:

1. Install the Codex CLI on your host machine.
2. Run codex login and choose "Sign in with ChatGPT".
3. Verify the token cache exists: ls ~/.codex/auth.json
4. Mount it into the container:

docker run -it \ -e FOAMAGENT_MODEL_PROVIDER=openai-codex \ -e FOAMAGENT_MODEL_VERSION=gpt-5.3-codex \ -v ~/.codex/auth.json:/root/.codex/auth.json:ro \ -p 7860:7860 \ leoyue123/foamagent

Foam-Agent searches for OAuth tokens at (first match wins):

• $CODEX_HOME/auth.json
• ~/.codex/auth.json
• ~/.clawdbot/agents/main/agent/auth-profiles.json

Security note: auth.json contains access tokens. Treat it like a password.

git clone https://github.com/csml-rpi/Foam-Agent.git cd Foam-Agent conda env create -n FoamAgent -f environment.yml conda activate FoamAgent

You also need OpenFOAM v10 installed and sourced. Follow the official installation guide and verify with:

echo $WM_PROJECT_DIR # should print e.g. /opt/openfoam10

Then run:

python foambench_main.py --output ./output --prompt_path ./user_requirement.txt

git clone https://github.com/csml-rpi/Foam-Agent.git cd Foam-Agent docker build -f docker/Dockerfile -t foamagent:latest . docker run -it \ -e OPENAI_API_KEY=your-key-here \ -p 7860:7860 \ foamagent:latest

Chinese-speaking users can join the Foam-Agent WeChat community by scanning the QR code below.

If you use Foam-Agent in your research, please cite our paper:

@article{yue2025foam, title={Foam-Agent: Towards Automated Intelligent CFD Workflows}, author={Yue, Ling and Somasekharan, Nithin and Zhang, Tingwen and Cao, Yadi and Chen, Zhangze and Di, Shimin and Pan, Shaowu}, journal={arXiv preprint arXiv:2505.04997}, year={2025} } @article{somasekharan2026cfdllmbench, title={CFDLLMBench: A Benchmark Suite for Evaluating Large Language Models in Computational Fluid Dynamics}, author={Somasekharan, Nithin and Yue, Ling and Cao, Yadi and Li, Weichao and Emami, Patrick and Bhargav, Pochinapeddi Sai and Acharya, Anurag and Xie, Xingyu and Pan, Shaowu}, journal={Journal of Data-centric Machine Learning Research}, year={2026}, url={https://openreview.net/forum?id=kTcH1MnkjY}, note={} }