SWMF

SWMF AI combines a small local CLI with task-specific skills for SWMF work. The swmf CLI returns evidence only. Skills decide which command to use first, what evidence matters, and how to answer. Everything runs locally — there is no server process.

System

flowchart TD
    CLIENT["AI agent / skills"] --> CLI["swmf CLI (one-shot, local)"]
    CLI --> T1["get-context"]
    CLI --> T2["get-evidence"]
    CLI --> T3["inspect"]
    CLI --> T4["compare"]

    T1 --> BACKEND["SWMF source tree, PARAM/XML metadata, examples, logs, run dirs"]
    T2 --> BACKEND
    T3 --> BACKEND
    T4 --> BACKEND

CLI commands

• swmf get-context for broad orientation, architecture, and cross-component questions.
• swmf get-evidence for source, docs, schema, lookup, and workflow evidence.
• swmf inspect for direct inspection of logs, PARAM files, XML, and run directories.
• swmf compare for deterministic diffs between two artifacts.
• swmf index build|refresh|status to manage the local knowledge index.

Each command prints a JSON result to stdout and exits non-zero on hard errors. Run swmf <command> --help for the full flag set.

Skills

Skills live in src/agent_assets/skills and are the main way the agent decides how to work.

Entry skills:

• swmf-explain for "how does this work?" questions.
• swmf-configure for setup and parameterization.
• swmf-build for build workflows.
• swmf-run for run workflows.
• swmf-debug for failure analysis.
• swmf-analyze for output interpretation and postprocessing.
• swmf-compare for change and difference questions.

Support skills:

• swmf-architecture
• swmf-exact-lookup
• swmf-implementation
• swmf-mflampa — SP/MFLAMPA SEP-model expert (modules, make test_mflampa, MFLAMPA params)
• swmf-params
• swmf-postproc

The shared discipline source is src/agent_assets/SWMF_CORE_DISCIPLINE.md.

AI-Assisted Install

If you are already inside an AI coding agent (Claude Code, GitHub Copilot, Codex CLI), copy the prompt below, fill in the two placeholders, and paste it into the agent. The agent will handle path discovery and run the right install command for you.

Placeholder	What to put
<AGENT>	claude, copilot-vscode, copilot-cli, or codex
<TARGET_DIR>	Absolute path to the project directory where SWMF AI should be installed

I want to install SWMF AI into <TARGET_DIR> for use with the <AGENT> agent.

The SWMF AI repository is at: <absolute path to this swmf-mcp-prototype directory>

Please complete the following steps in order:

1. Run `make` inside the swmf-mcp-prototype repository to bootstrap the Python
   runtime and build the knowledge index. Wait for it to succeed before continuing.

2. Find the SWMF source root. Check in order:
   a. The environment variable $SWMF_ROOT if set.
   b. A directory named "SWMF" that is a sibling of the swmf-mcp-prototype directory.
   c. Any other existing path named "SWMF" visible from the current machine.
   Report the resolved absolute path, or ask me if none is found.

3. Find SWMFSOLAR if it exists. Check in order:
   a. A directory named "SWMFSOLAR" that is a sibling of the SWMF root found above.
   b. A directory named "SWMFSOLAR" that is a sibling of the swmf-mcp-prototype directory.
   Report the resolved absolute path, or skip if none exists.

4. Run `which idl` to find the IDL executable. Report the path, or skip if not found.

5. Run the install command, substituting the paths discovered above:

   make install \
     AGENT=<AGENT> \
     TARGET_DIR=<TARGET_DIR> \
     SWMF_ROOT=<path from step 2> \
     [SWMF_IDL_EXEC=<path from step 4>] \
     [SWMFSOLAR_ROOT=<path from step 3>]

   Omit SWMF_IDL_EXEC and SWMFSOLAR_ROOT if those paths were not found.

Install & Usage

Requirements:

• Python 3.11+
• make
• network access the first time dependencies are resolved with uv

Bootstrap the local runtime and build the local knowledge index:

make

make installs uv if needed, reuses a valid .venv when possible, creates or syncs the environment when needed, and builds the local knowledge index used by the swmf CLI.

Install one agent bundle:

make install AGENT=claude
make install AGENT=copilot-vscode SWMF_ROOT=/data/SWMF
make install AGENT=copilot-cli SWMF_ROOT=/data/SWMF SWMFSOLAR_ROOT=/data/SWMFSOLAR
make install AGENT=codex SWMF_ROOT=/data/SWMF SWMF_IDL_EXEC=/path/to/idl
make install AGENT=claude TARGET_DIR=/path/to/workspace SWMF_ROOT=/data/SWMF

AGENT is required for make install and must be one of claude, copilot-vscode, copilot-cli, or codex.

SWMF_ROOT defaults to ./SWMF relative to this repository. SWMF_IDL_EXEC is optional and is written only when passed. SWMFSOLAR_ROOT is optional; when omitted during make install, the installer auto-detects it and writes only the first existing match from:

• a sibling of the chosen SWMF_ROOT
• ./SWMFSOLAR in this repository
• TARGET_DIR/SWMFSOLAR

TARGET_DIR defaults to this repository. When TARGET_DIR points elsewhere, make install also creates TARGET_DIR/.swmf_mcp_server as a symlink back to this repo so the generated launcher can reach the project venv.

Unlike make, make install bootstraps the Python runtime if needed but does not rebuild the knowledge index.

make install writes a self-contained swmf launcher at TARGET_DIR/.swmf_ai/swmf (with SWMF_ROOT and any IDL/SWMFSOLAR paths baked in), generates the agent instruction file (a header naming the launcher path, followed by the shared SWMF discipline), and symlinks the agent skill tree from src/agent_assets/skills.

When the agent is launched in your project directory, it loads the skills automatically and runs the swmf CLI through the generated launcher.

Example user prompts:

• "Explain how GM couples to IE in this setup."
• "Find evidence for how DoCoupleGMIE is defined and used."
• "What entrypoints matter for configuring GM?"
• "Inspect this PARAM.in and summarize likely issues."
• "Compare these two run directories and summarize meaningful changes."