geant4_claude
A plugin that lets you build, run, and analyze your own Geant4
simulation by describing what you want in plain language — no slash
commands, no menu. You say "set up a Geant4 project" or "simulate a
1 GeV e⁻ on a lead block" and the matching skill auto-triggers.
Works on both Claude Code and OpenAI Codex CLI with the same skills,
the same engine, and the same analysis stack. Geant4 and ROOT live in a
pinned apptainer image; analysis runs on the host with
uproot.
Status: v0.1.0. Everything is a skill now — the plugin ships no
slash commands. Thirteen skills cover the flow: geant4 (the
orchestrator / front door), geant4-init (scaffold a project),
geant4-task (create a simulation-task subdir), geant4-detector,
geant4-example, geant4-preview, geant4-build,
geant4-run, geant4-analyze, geant4-validate, plus the
reference skills geant4-geometry, geant4-physics-list, and
geant4-analysis. The procedural skills are content-neutral — they
accept any user-supplied main.cc and any output schema. The
geant4-detector skill writes standalone GDML (including an
optical/RINDEX path) for use with whatever main.cc you bring. The
geant4-example skill is a self-contained smoke test that drops a
working demo into a task so you can confirm the toolchain works
on your machine before writing any of your own code.
Works on Claude Code and Codex CLI
Same skills, same engine (bin/g4run via apptainer), same host-side
uproot analysis. You drive the plugin by describing tasks in natural
language; the relevant skill triggers on its own.
Claude Code:
/plugin marketplace add zhaozhiwen/geant4_claude
/plugin install geant4-claude@geant4-claude
Codex CLI:
codex plugin marketplace add zhaozhiwen/geant4_claude
codex plugin add geant4-claude@geant4-claude
Codex one-command install is a work in progress. Codex's marketplace only
packages a plugin from a plugins/<name>/ subdirectory of real files, and
this plugin currently lives at the repo root — so the plugin add above won't
snapshot it as-is. Until a Codex packaging step lands, install by copying the
plugin into a subdir the marketplace points at (plugins/geant4-claude/).
Once installed, the plugin runs fully on Codex — skill discovery, the
.g4c/ engine pointer, and the ensure_venv.sh venv bootstrap are all
verified on codex v0.135.0.
How skills find the engine, CLI-neutrally: the geant4-init skill
scaffolds your project and records the shared engine pointer at .g4c/
(a small shim that resolves the current bin/g4run live, plus an env
file); every other skill — including those run from a task subdir —
locates the runtime by walking up to .g4c/, the same way on either CLI,
and a plugin update never strands the project. On both CLIs, geant4-init also
bootstraps the Python venv on first scaffold — the plugin ships no
session-start hook, so the install is skill-driven and lazy.
Requirements
- apptainer ≥ 1.4 on Linux.
- Python 3.9+ on the host with
uproot numpy matplotlib
(only needed for the geant4-analyze skill).
- ~2.5 GB of disk for the cached container image.
- Claude Code or OpenAI Codex CLI with plugin support.
The plugin will pull
docker://ghcr.io/gemc/g4install:11.4.0-almalinux-9.4 on first use; the
tag is pinned in bin/g4run and nowhere else (read it back
with bin/g4run image-tag).
Install
See Works on Claude Code and Codex CLI
above for the install lines. On Claude Code, the marketplace-add command
registers this repo as a marketplace (it ships
.claude-plugin/marketplace.json alongside the plugin manifest) and the
install command pulls the plugin from it; /plugin update handles
upgrades.
Manual git clone (either CLI):
git clone https://github.com/zhaozhiwen/geant4_claude.git ~/.claude/plugins/geant4_claude
# then enable it in your CLI's plugin manager
If you cloned a fork, replace zhaozhiwen accordingly. The plugin manifest is at .claude-plugin/plugin.json.
What happens when you enable the plugin
Two things get set up automatically — neither needs your action beyond approving once. The first is registered when the CLI loads the plugin; the second is seeded lazily on first use:
- deepwiki MCP server is registered from
.mcp.json. Claude Code prompts once to approve the external server (https://mcp.deepwiki.com/mcp, no auth, no key); approve it and Claude gains three tools (mcp__deepwiki__ask_question, read_wiki_structure, read_wiki_contents) for asking Geant4 questions in-loop. Used by the plugin as orientation only — answers are LLM-grounded and must be verified against actual Geant4 source before they land in any synthesis. See docs/DESIGN.md §"deepwiki MCP".
