Whittle
AI-powered engineering design agent
Ask AI about Whittle
Powered by Claude Β· Grounded in docs
I know everything about Whittle. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Whittle - AI-Powered CFD Assistant
An AI-powered assistant for CFD case setup and mesh generation, supporting multiple CFD solvers through a plugin architecture. Whittle integrates with Claude Desktop to provide an intelligent interface for OpenFOAM and other CFD software workflows.
Prerequisites
Before installing Whittle, ensure you have:
- Python 3.12+ installed on your system
- Docker Desktop installed and running
- Claude Desktop installed and configured
- uv package manager (recommended) or pip
Installation
1. Clone the Repository
git clone <repository-url>
cd Whittle
2. Install Dependencies
Option A: Using uv (Recommended)
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync
Option B: Using pip
pip install -e .
3. Set Up Environment Variables
Create a .env file in the project root with your API keys:
# For OpenAI GPT models (optional)
OPENAI_API_KEY=your_openai_api_key_here
# For Claude models (required for Claude Desktop integration)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
4. Configure Claude Desktop
Whittle uses the Model Context Protocol (MCP) to communicate with Claude Desktop. You need to configure Claude Desktop to connect to the Whittle MCP server.
- Open Claude Desktop
- Go to Settings β Model Context Protocol
- Add a new server with the following configuration:
{
"mcpServers": {
"whittle": {
"command": "/path/to/bin/uv",
"args": ["--directory", "/path/to/Whittle/whittle/src/api", "run", "server.py"]
}
}
}
Important Notes:
- Replace
/path/to/your/whittle/projectwith the actual absolute path to your Whittle project directory - The
PYTHONPATHenvironment variable is crucial for the server to find the Whittle modules - Make sure the path uses forward slashes (/) even on Windows
5. Pull OpenFOAM Docker Image
Whittle uses Docker to run OpenFOAM commands. Pull the required image:
docker pull opencfd/openfoam-run:latest
Usage
Starting Whittle with Claude Desktop
- Launch Claude Desktop
- Start a new conversation
- Whittle will automatically connect via MCP and provide CFD tools
Basic Workflow
Once connected, you can interact with Whittle through Claude Desktop using natural language:
- Set up a case: "Help me set up an OpenFOAM case for airfoil simulation"
- Generate mesh: "Generate a mesh for my case"
- Run simulation: "Run the simulation"
- Check mesh quality: "Check the mesh quality"
Available Tools
Whittle provides several specialized tools for CFD workflows:
create_cfd_case_without_generating_mesh- Set up initial case files (controlDict, fvSchemes, etc.)foam_block_mesh_generation- Generate simple meshes using blockMeshfoam_snappy_hex_mesh_generation- Generate complex meshes using snappyHexMeshrun_openfoam_simulation- Run OpenFOAM solvers (simpleFoam, pimpleFoam, etc.)check_foam_mesh_quality- Check mesh quality and topologyedit_file- Modify case fileshelp_tool_selection- Get guidance on which tool to use
Example Conversation
You: "I want to simulate flow around a NACA 0012 airfoil at 10 degrees angle of attack"
Claude: I'll help you set up an OpenFOAM case for your airfoil simulation. Let me create the necessary case files first.
[Claude uses create_cfd_case_without_generating_mesh tool]
You: "Now generate a mesh for this case"
Claude: I'll generate a mesh using blockMesh for your airfoil case.
[Claude uses foam_block_mesh_generation tool]
You: "Run the simulation"
Claude: I'll run the simulation using the simpleFoam solver for your incompressible steady-state case.
[Claude uses run_openfoam_simulation tool]
Project Structure
whittle/
βββ __init__.py # Package initialization
βββ config.py # Configuration settings
βββ src/ # Source code
βββ __init__.py
βββ api/ # MCP server and API
β βββ server.py # Main MCP server
β βββ stdio_server.py # Alternative stdio server
βββ application/ # Application layer
β βββ cfd_interactor.py
β βββ llm_agent_interactor.py
βββ entities/ # Domain entities
β βββ cfd_software.py
β βββ llm_agent.py
βββ infra/ # Infrastructure layer
β βββ registry.py
βββ UI/ # User interface
βββ cli.py
Supported CFD Software
Currently supported CFD solvers:
- OpenFOAM - Full support for case setup, mesh generation, and simulation
- SU2 - Basic support (planned expansion)
Troubleshooting
Common Issues
-
"Module not found" errors
- Ensure
PYTHONPATHis set correctly in Claude Desktop config - Use absolute paths in the configuration
- Ensure
-
Docker connection issues
- Verify Docker Desktop is running
- Check that the OpenFOAM image is pulled:
docker images | grep openfoam
-
API key errors
- Verify your
.envfile contains the correct API keys - Ensure the keys have sufficient credits/permissions
- Verify your
-
MCP connection failures
- Restart Claude Desktop after configuration changes
- Check the server path in Claude Desktop config
- Verify Python can find the Whittle modules
Getting Help
If you encounter issues:
- Check the troubleshooting section above
- Verify all prerequisites are installed correctly
- Ensure Docker is running and accessible
- Check that Claude Desktop can connect to the MCP server
Adding New CFD Software
Whittle uses a plugin architecture. To add support for new CFD software:
- Create a new class in
whittle/src/entities/cfd_software.py - Implement the required methods
- Register the software in
whittle/src/infra/registry.py
Dependencies
- Python 3.12+
- Docker Desktop with OpenFOAM image (
opencfd/openfoam-run:latest) - Claude Desktop
- uv (recommended) or pip
- Anthropic API key (required)
- OpenAI API key (optional)
License
[Add your license information here]
