Foam-Agent

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.

Key Features

• 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.

Quick Start

1. Pull and run the Docker image

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

2. Write your prompt

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.

3. Run

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.

Configuration

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.

LLM Provider and Model

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

Embedding Provider and Model

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

API Keys

Input Writer Generation Mode

Set in src/config.py via input_writer_generation_mode:

Recommended Models

We recommend Anthropic Claude Opus 4.6 for best results.

Advanced Usage

Custom Mesh Files

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

Skill / MCP Integration (Claude Code, Cursor, Windsurf, etc.)

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.

Quick Setup (Local Install)

# 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.

Quick Setup (Docker)

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).

Available MCP Tools

All tools generate output following Foundation OpenFOAM v10 conventions.

Claude Code Skill

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.

Codex OAuth Sign-in (No API Key)

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.

Manual Installation (Without Docker)

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 Foundation OpenFOAM v10 (openfoam.org) installed and sourced. ESI OpenFOAM (openfoam.com) is not compatible. 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

Building the Docker Image from Source

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

Troubleshooting

OpenFOAM version: Foam-Agent targets Foundation OpenFOAM v10 (openfoam.org) exclusively. All generated case files, dictionary names, and solver binaries follow Foundation v10 conventions. ESI OpenFOAM (openfoam.com, e.g., v2312, v2406, v2512) is not supported — generated files will not work without manual adaptation. The Docker image includes Foundation OpenFOAM v10 pre-installed.

Community

Join the WeChat community

Chinese-speaking users can join the Foam-Agent WeChat community by adding the volunteer's WeChat account: ZDSJTUCFD. The volunteer will invite you to the group.

Citation

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={}
}

Star History