⚛ 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

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

magnus login

magnus local start

magnus run hello-world

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:

[!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:

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

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:

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.

Skills

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.

[!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.