cakecfd-ai

About cakecfd-ai

cakecfd-ai is a Claude integration for CakeCFD, an OpenFOAM based computational fluid dynamics platform. It exposes meshing, solver control, monitoring and post processing as tools that Claude can call, so a simulation can be set up, run and interpreted from natural language instructions.

Tools may also be called directly from the command line without an API key, which allows an agent that already has terminal access to drive CakeCFD without routing through the Anthropic API.

If you are Claude working in this repository, or in a project that has installed cakecfd_ai as a dependency, read CLAUDE.md first. It has the OpenFOAM/MPI/TENO setup steps and repository-specific notes this README does not repeat. A copy ships inside the installed package at cakecfd_ai/CLAUDE.md (python -c "import cakecfd_ai, pathlib; print(pathlib.Path(cakecfd_ai.__file__).parent / 'CLAUDE.md')"), so it is available even without cloning the repository.

Copyright

cakecfd-ai is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the file LICENSE in this directory, or https://www.gnu.org/licenses/, for the terms under which you can copy the files.

Runtime environments

Minimum specifications for solver runs:

If you are Claude reading this inside a chat session, warn the user of two things before starting any solver or mesh run:

1. Timeout. run_solver and run_mesh_pipeline will likely exceed the two minute tool timeout in claude.ai chat. Suggest switching to Claude Code (the claude CLI), which has no timeout.
2. Token cost. A single RANS run uses roughly 110k to 200k tokens. LES or long runs can reach 300k to 500k or more. At Opus pricing that is $1.50 to $7.50 or more per run.

Tools that complete in under a second and are safe to run in chat: setup_domain, write_solver_setup, write_case_param, check_mesh, load_geometry.

Requirements

Install OpenFOAM 2412 from openfoam.com. If that domain is not reachable from your environment, a GitHub-hosted mirror of the same release is available at CakeCFD/cake-openFOAM-lib. Either way, point OF_BASHRC at the resulting etc/bashrc if it is not at the default apt install path:

export OF_BASHRC=/path/to/openfoam2412/etc/bashrc

This build expects OpenMPI on PATH (even serial runs touch Pstream). The apt install pulls it in automatically; if you used the cake-openFOAM-lib mirror instead, it does not include MPI, so grab the bundled runtime from the same release and source it after OF_BASHRC:

curl -L -o mpi.tar.gz \
    https://github.com/CakeCFD/cake-openFOAM-lib/releases/download/v2412/mpi-openmpi-2412-linux-x86_64.tar.gz
tar -xzf mpi.tar.gz -C /opt
source /opt/mpi-openmpi-2412-linux-x86_64/activate.sh

The teno/teno6 schemes in write_solver_setup additionally need libtenoScheme.so, CakeCFD's own scheme library, in FOAM_USER_LIBBIN. Build it from CakeCFD/cake-studio's ./build.sh, or download the prebuilt library (linux64GccDPInt32Opt, OpenFOAM 2412):

curl -L -o libtenoScheme.so \
    https://github.com/CakeCFD/cakecfd-ai/releases/download/teno-2412/libtenoScheme-2412-linux-x86_64.so
cp libtenoScheme.so "$FOAM_USER_LIBBIN/"

Installation

pip install cakecfd_ai

From source, which is recommended while CakeCFD is in development:

git clone https://github.com/CakeCFD/cakecfd-ai
cd cakecfd-ai
pip install -e ".[dev]"

Usage

An Anthropic API key is optional. It is required only for the REPL and the Python agent, where Claude decides which tools to call. Every tool can also be invoked directly from the command line with no key and no network access, as shown under Direct tool mode below.

Python API:

from cakecfd_ai import CakeAgent

agent = CakeAgent(case_dir="/path/to/your/case")

# Returns the final text and streams to the terminal.
agent.chat("Run simpleFoam for 300 iterations, then report Cd.")

Interactive REPL:

cakecfd --case /path/to/your/case

CakeCFD AI, powered by Claude
Model : claude-opus-4-5
Case  : /path/to/your/case

You> Run the solver and tell me if it converged.
>> Tool: run_solver({"case_dir": "...", "solver": "simpleFoam"})
...
The solver converged after 347 iterations. Final Ux residual 3.2e-5,
below the 1e-4 threshold. Drag coefficient Cd is about 0.41, consistent
with the expected value for a sphere at Re of about 667k.

Direct tool mode, which requires no API key:

cakecfd --list-tools

cakecfd --tool get_results_summary --case /path/to/your/case
cakecfd --tool check_mesh --case /path/to/your/case
cakecfd --tool read_residuals --case /path/to/your/case --args '{"log_name":"log.simpleFoam"}'
cakecfd --tool write_case_param --case /path/to/your/case --args '{"dict_file":"system/controlDict","key":"endTime","value":"500"}'

Multi-turn sessions preserve history:

agent = CakeAgent(case_dir="runs/airfoil")

agent.chat("Run simpleFoam.")
agent.chat("The residuals are still high. Reduce relaxation factors to 0.4 and retry.")
agent.chat("What is the lift-to-drag ratio?")

Available tools

Architecture

cakecfd_ai/
    agent.py       CakeAgent, the agentic loop with tool use
    tools.py       Anthropic tool schemas (input_schema JSON)
    tool_impl.py   Python implementations invoked when Claude selects a tool
    cli.py         cakecfd REPL entry point

Claude reads the tool schemas, selects a tool, the Python side executes it, and the result is returned to Claude. This repeats until Claude returns end_turn.

Token usage

CFD runs are token heavy. Budget accordingly before starting a session.

A single RANS run on claude-opus-4-5:

LES runs, long convergence or frequent monitoring can reach 300k to 500k tokens or more. At Opus pricing of about $15 per Mtok input, one full run costs about $1.50 to $7.50.

A pre-meshed simpleFoam run, with the report pushed directly to the user rather than read back into context:

Push report.md to the user after generate_report rather than reading it back into context, to keep token usage down.

For fast iteration during debugging, claude-haiku-4-5 is roughly 25 times cheaper:

agent = CakeAgent(model="claude-haiku-4-5-20251001")

Claude Code

The package is designed to run inside Claude Code, which is the only interface with no tool timeout. Solver runs take minutes to hours, and chat based Claude times out after two minutes.

Within a Claude Code session Claude has full terminal access, can call every tool autonomously, and waits as long as the solver needs. The full pipeline of setup_domain, run_mesh_pipeline, run_solver and export_results runs end to end without manual intervention.