⚛ Collider-Agent

An End-to-end Architecture for Collider Physics and Beyond

From a LaTeX Lagrangian to a publication-ready figure — fully automated.

Overview • Quickstart • Installation • Examples • Python Agent • Citation

中文

Overview

Collider-Agent enables AI coding agents (Claude Code, Cursor, Windsurf, and more) to autonomously reproduce collider phenomenology results from physics papers. It combines specialized sub-agents and reusable skill modules that interface with standard HEP tools via the Magnus cloud platform — no local HEP software installation required.

Full pipeline, fully automated:

• Parse a LaTeX Lagrangian and generate a FeynRules model
• Validate the model and produce a UFO output for MadGraph5
• Run parton-level and showered event generation with MadGraph5 + Pythia8
• Apply detector simulation (Delphes) and analysis cuts (MadAnalysis5)
• Generate kinematic distributions, cutflow tables, exclusion contours in parameter space, etc.

Roadmap

Status	Feature
✅	FeynRules model generation from LaTeX Lagrangian
✅	FeynRules model validation (Hermiticity, mass diagonalization, kinetic terms)
✅	UFO model generation for MadGraph5
✅	MadGraph5 event generation with Pythia8 parton shower
✅	Delphes detector simulation
✅	MadAnalysis5 normal mode analysis
✅	Multi-agent orchestration for full pipeline
⬜	MadAnalysis5 expert mode support
⬜	Fine-grained parameter tuning for Pythia and other packages
⬜	More paper reproduction examples (contributions welcome!)

Installation

Prerequisites

• Claude Code — recommended; provides full support for both sub-agents and skills

  Other agents with skills support also work (skills only, no sub-agents): Cursor, Windsurf, Gemini CLI, Cline, Goose, Roo Code, and more

• Python 3.10+ (requires magnus-sdk>=0.7.0)

Setup

1. Clone the repository:

git clone https://github.com/HET-AGI/ColliderAgent.git
cd ColliderAgent

2. Connect to the Magnus platform:

First, install the Magnus SDK:

pip install magnus-sdk

☁️ Option A: Connect to an existing cloud instance

If you have access to a cloud-hosted Magnus instance, authenticate with:

magnus login

Enter your server URL and API key when prompted. All subsequent commands are routed to the remote backend automatically.

🖥️ Option B: Local deployment

[!WARNING] Local Magnus deployment is under active development and may contain known issues. It is not recommended for general use at this time. A stable release is expected no later than March 29, 2026.

Additional prerequisites: Docker (daemon running), Node.js (optional, enables the Web UI)

Start the local backend:

magnus local start

This fetches the Magnus source, installs backend dependencies, starts the server on port 8017, and creates a local database and user account. If Node.js is installed, a Web UI is also launched at http://localhost:3011.

Verify the setup:

magnus run hello-world

A successful run prints Hello from Magnus! after pulling the required container image.

For full Magnus documentation and deployment options, see github.com/Rise-AGI/magnus.

3. Copy agents and skills to your agent's configuration directory.

For Claude Code (full support: sub-agents + skills):

cp -r src/agents ~/.claude/agents
cp -r src/skills ~/.claude/skills

For other agents (skills only):

# Replace <skills-path> with the global skills path for your agent (see table below)
cp -r src/skills <skills-path>

Supported agents and their global skills paths:

Agent	Global skills path
Claude Code	~/.claude/skills/
Cursor	~/.cursor/skills/
Windsurf	~/.codeium/windsurf/skills/
GitHub Copilot	~/.copilot/skills/
Gemini CLI	~/.gemini/skills/
Cline / Warp	~/.agents/skills/
Goose	~/.config/goose/skills/
Roo Code	~/.roo/skills/
OpenCode	~/.config/opencode/skills/
Codex	~/.codex/skills/

Tip

Project-scoped installation is also supported. Copy src/skills/ into .claude/skills/ (or the equivalent directory for your agent) at the root of your working directory to scope the skills to that project only.

4. Restart your agent to load the new agents and skills.

5. (Optional) Activate the Wolfram Engine license:

🔬 Configure Mathematica / Wolfram Engine license

The FeynRules-based blueprints (feynrules-model-validator, ufo-generator) require a Wolfram Engine license. Because the license is tied to the machine identity of the container rather than the host, activation must be performed inside the container itself.

1. Register a free Wolfram ID at wolfram.com/engine/free-license

2. Run the activation inside the container:

mkdir -p ~/.wolfram-container-license
docker run -it --rm \
  -v ~/.wolfram-container-license:/root/.WolframEngine/Licensing \
  git.pku.edu.cn/het-agi/mma-het:latest wolframscript

3. Follow the interactive prompts to enter your Wolfram ID and password.

The license file (mathpass) is written to ~/.wolfram-container-license/ on the host, which all subsequent FeynRules blueprint runs mount automatically. This step is only needed once.

Quickstart

The fastest way to try Collider-Agent is to run a standard-model dilepton invariant mass plot — a classic parton-level check — directly from the command line:

claude -p "Plot the dilepton invariant mass distribution for parton-level pp -> l+l- process at the 14 TeV LHC in the SM." --dangerously-bypass-permissions

This runs the full pipeline non-interactively: MadGraph5 generates the events via Magnus, and the agent produces a normalized $m_{\ell\ell}$ histogram in your working directory.

Usage

Basic Workflow

1. Prepare a detailed Markdown prompt (for example, prompt.md) describing the collider analysis you want to run, including the Lagrangian, collider process, event selection, and parameter scan strategy, much like you would write your own research note or paper draft (see paper-reproduction/ for examples)

2. Start your agent and provide the prompt:

claude -p "Execute the analysis following prompt.md"

3. The system orchestrates the full pipeline:
   • Parse the Lagrangian and generate a FeynRules model
   • Validate and generate the UFO model
   • Run MadGraph5 simulations with Pythia8 / Delphes
   • Apply analysis cuts with MadAnalysis5
   • Generate the analysis outputs, such as kinematic distribution plots, parameter exclusion regions, and any other results requested in the user prompt

Standalone Tasks

The agent can also be used for individual sub-tasks, without running the full collider-phenomenology pipeline. For example, you can ask it to:

• translate a Lagrangian written in standard LaTeX-based physics notation into a FeynRules .fr model file
• generate events for a process at the LHC based on a UFO model file
• analyze Monte Carlo events with MadAnalysis to produce a kinematic distribution plot

For instance, you may provide a prompt like:

claude -p "Given the Lagrangian in prompt_lagrangian.md, generate a FeynRules .fr model and export the corresponding UFO files"

Here, prompt_lagrangian.md contains the Lagrangian written in standard LaTeX physics notation.

Example Prompts

The paper-reproduction/ directory contains example prompts to reproduce figures in the following papers:

arXiv ID	Topic	Figures
hep-ph/9909255	$e^+ e^- \to \mu^+ \mu^- $ affected by KK tower of gravitons	2
1308.2209	Heavy Neutrinos production at the LHC	3
1605.02910	Exclusion parameter region from Drell-Yan process at the LHC for a $U(1)'$ model	1, 10
1701.05379	ALP Effective Field Theory and Collider Signatures	8
1811.07920	Exclusion parameter region from mono-$\tau$ search at the LHC for the $U_1$ leptoquark model	3
2005.06475	Leptoquark production from lepton-Quark collisions at the LHC by using LUXlep PDF	2
2103.02708	$p p \to Z^\prime \to \ell^+ \ell^-$ at the LHC in the SSM and $E_6$ inspired $Z^\prime$ scenario	4
2104.05720	Searching for Leptoquarks via $\mu^+ \mu^- \to b \bar{b}$ process at Future Muon Colliders	11, 12

Repository Structure

ColliderAgent/
├── src/
│   ├── agents/                        # Sub-agent definitions (Claude Code)
│   │   ├── model-generator.md
│   │   ├── collider-simulator.md
│   │   ├── event-analyzer.md
│   │   └── pheno-analyzer.md
│   └── skills/                        # Agent skill modules (all agents)
│       ├── feynrules-model-generator/
│       ├── feynrules-model-validator/
│       ├── ufo-generator/
│       ├── madgraph-simulator/
│       ├── madanalysis-analyzer/
│       ├── pheno-pipeline-orchestrator/
│       └── magnus/
├── python-agent/                      # Standalone ADK agent (Python API)
├── scripts/                           # Magnus cloud blueprint scripts
├── paper-reproduction/                # Example prompts from paper
│   ├── 1308.2209/
│   ├── 1605.02910/
│   └── ...
├── pyproject.toml
└── README.md

Sub-agents

Note

Sub-agents are currently supported by Claude Code only. Users of other agents can use the skills directly via the agent's built-in skill invocation mechanism.

Agent	Description
model-generator	LaTeX → FeynRules → UFO pipeline
collider-simulator	MadGraph5 event generation with Pythia8 / Delphes
event-analyzer	MadAnalysis5 cut-flow and histogram analysis
pheno-analyzer	Orchestrates the full phenomenology study

Skills

Skill	Description
feynrules-model-generator	Generate .fr model files from LaTeX Lagrangians
feynrules-model-validator	Validate .fr models via Mathematica checks
ufo-generator	Export FeynRules models to UFO format
madgraph-simulator	Run MadGraph5_aMC@NLO event generation
madanalysis-analyzer	Perform cut-flow analysis and produce histograms
pheno-pipeline-orchestrator	Coordinate the end-to-end phenomenology pipeline
magnus	Interface with the Magnus cloud HEP platform

Python Agent

In addition to the skill-based interface, ColliderAgent ships a standalone Python ADK agent and a set of Magnus cloud blueprint scripts for users who want direct programmatic access to the pipeline — without Claude Code or any other AI coding assistant.

Module	Description
python-agent/	Google ADK agent that accepts natural-language physics tasks and orchestrates the full pipeline via Python API. Includes uv-based setup, interactive CLI.py, and a full test suite.
scripts/	Entry-point scripts executed by Magnus blueprint containers. Each script corresponds to a named blueprint (validate-feynrules, generate-ufo, madgraph-compile, etc.) called by the agent's tools.

Note

If you only want to use Collider-Agent through Claude Code (or another AI agent), you don't need these directories. They are intended for programmatic access, custom integrations, and pipeline development.

See the individual READMEs for installation and usage details:

• python-agent/README.md
• scripts/README.md

Citation

If you use Collider-Agent in your research, please cite:

@article{Qiu:2026iby,
    author = "Qiu, Shi and Cai, Zeyu and Wei, Jiashen and Li, Zeyu and Yin, Yixuan and Cao, Qing-Hong and Liu, Chang and Luo, Ming-xing and Yuan, Xing-Bo and Zhu, Hua Xing",
    title = "{An End-to-end Architecture for Collider Physics and Beyond}",
    eprint = "2603.14553",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    reportNumber = "CPTNP-2026-012",
    month = "3",
    year = "2026",
    url = "https://github.com/HET-AGI/ColliderAgent"
}

Please also cite the HEP tools used in your analysis, including FeynRules, MadGraph5_aMC@NLO, Pythia8, Delphes, and MadAnalysis5

Acknowledgments

We thank the developers of FeynRules, MadGraph5_aMC@NLO, Pythia8, Delphes, and MadAnalysis5 for their excellent tools that make this work possible.