FUSION

Framework for Unified Scientific Intelligence in Open Nuclear physics
FU ▸◂ SION

vibeinscience.com · MIT · 26 skills · 61,167 offline literature pages · 中文

Beta release, tested in public

v0.1.0 is the first public build. It works, it is used daily by its author,
and it has not been used by anyone else. What breaks for you is the point.

Three things you will probably hit

• macOS blocks the first run. The binary is not signed. Run
  xattr -d com.apple.quarantine fusion and it will start.
• Do not begin with TALYS. It downloads about 11 GB. Try FRESCO or CCFULL
  first; they build in a minute or two.
• Cold-start installs are the least tested part. All twenty codes have been
  exercised once on a bare Linux box: thirteen installed and verified cleanly,
  four stopped with a message naming the missing dependency, and for the last
  three the harness rather than the skill was the limit. If a code fails to
  build on your machine, that is the single most useful thing you can report.

What to report, in order of value

1. A result that looked right and was wrong. The whole reason this project
   exists is that a general agent writes a plausible FRESCO deck with the wrong
   radius convention. If FUSION does something of that kind, we want the deck,
   the number, and what it should have been. A plausible but wrong result is
   the failure we fear most, and the one users are least likely to report.
2. A code that will not install, with the error and your OS and compiler.
3. Anything that felt stupid. Every awkward thing in the first-run flow was
   found by one person trying it and saying so plainly. That works.
4. Which code you wish had a skill.

Open an issue, or write to
[email protected]. Chinese or English, whichever you prefer.

An agent that already knows how to drive the open-source codes nuclear
physicists actually use, and that carries the nucl-th literature with it,
offline.

Running a nuclear-physics code for the first time is mostly not physics. It is
finding the source, getting it to compile, learning an input format documented
in a 300-page manual or not at all, and then not knowing whether the number that
came out is right.

A general-purpose coding agent fails at this in a specific and dangerous way.
Ask one for a FRESCO deck and it will hand you a plausible file with the wrong
radius convention. The deck runs. The cross section is 20% wrong. Nothing warns
you.

FUSION ships one expert skill per code. Each teaches an agent to install that
code from its own upstream source, write its inputs correctly, run it, parse the
output, recognise its failure modes, and check the answer against a benchmark
with a stated tolerance.

Quickstart

# 1. FUSION itself
git clone https://github.com/jinleiphys/FUSION.git && cd FUSION

# 2. the CLI, into the clone (pick your platform from the releases page)
curl -fsSL https://github.com/jinleiphys/FUSION/releases/latest/download/fusion-darwin-arm64.tar.gz | tar -xz
xattr -d com.apple.quarantine fusion          # macOS only, see below

# 3. work
./fusion

That is the whole thing: ./fusion run inside the clone finds all 26 skills
and the knowledge base with no configuration at all.

Those two commands are the only ones that need GitHub. If you are installing
onto a lab server rather than your own machine, check that it can reach
github.com first: compute nodes often cannot, and the symptom is a one to two
minute hang and then Failed to connect to github.com port 443. Setting
http_proxy and https_proxy for those two commands is enough. Nothing
afterwards needs GitHub, because each code is fetched from its own upstream on
first use and the knowledge base is already in the clone.

To run it from anywhere instead of ./fusion, move it onto your PATH:

mkdir -p ~/.local/bin && mv fusion ~/.local/bin/

# if `fusion` is then "command not found", ~/.local/bin is not on your PATH.
# macOS does not put it there by default:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec zsh

Builds for macOS and Linux, x64 and arm64, are on the
releases page. They are not
signed or notarised, so macOS blocks the first run until you clear the
quarantine attribute as above. If you would rather not run an unsigned binary,
fusion is a rebranded opencode and
everything here works under a stock opencode install too.

There is no configuration step. Started from inside the clone, the agent
finds all 26 skills on its own. Ask it something and it will reach for the right
one.

The first time you ask it anything, it offers to set itself up, and never
asks again once you have. The offer arrives with your first message rather than
at the splash screen, and it does not hold up the thing you actually asked for. Accept and it walks you through your model, the areas you work in, the
colour theme, and a private space seeded from your own papers: the topics your
work carries, who you write with, who cites you inside the corpus. Decline and
it gets straight to what you asked. That private space is created outside this
repository, so nothing personal can reach a public clone.

You can also run it whenever you like by saying set up fusion, or directly:

python3 scripts/fusion_init.py        # --dry-run to watch it decide without writing

Then ask for what you want, in words:

run a CDCC calculation for d+58Ni at 21.6 MeV and compare the elastic angular
distribution with whatever EXFOR data exists

It handles the rest, building FRESCO from source if your machine lacks it.

The clone transfers about 256 MB and takes roughly 950 MB on disk, nearly all
of it the knowledge base. If you want the skills without it, skip the clone and
point your agent at the index instead:

// ~/.config/opencode/opencode.json
{ "skills": { "urls": ["https://raw.githubusercontent.com/jinleiphys/FUSION/main/skills/"] } }

Verified: on a machine with no clone, that pulls and caches the full skill set.

Requirements: git, make, gfortran, a C++ compiler, python3. Individual
skills pull their own extra dependencies and say so before they do.

What is in it

26 skills. Twenty drive a specific code, one is a fitting companion, one
retrieves experimental data, one searches the offline knowledge base, two
(literature-wiki, research-profile) maintain your own persistent research
wikis, and one sets FUSION up.

Each skill's SKILL.md states what it covers and how it was verified. What is
in, what was dropped, and why: skills-catalog.md.

61,167 pages of literature, offline, in kb-wiki/: one page per
paper for 61,059 arXiv nucl-th papers, 108 topic pages, and citation and
semantic-relation layers connecting them. The agent reads it with plain grep,
guided by the kb-search skill. No server, no API key, no network.

Those pages are machine-generated summaries and they can be wrong. Read
kb-wiki/README.md before relying on one, and cite the
paper, never the page.

It is not tied to one agent

The skills are the project. The bundled CLI is one way to run them, not the
point. If you already work in Claude Code or Codex, clone the repository and
use it there; you can ignore the binary in the quickstart entirely, and you will
be on a better-tested path than the fork, which exists mainly so that someone
with no agent installed still has something to run.

Skills are directories of Markdown and shell scripts. Each ships both entry
files, so all three common agents can load them.

The Codex entry files are generated pointers rather than hand-written condensed
mirrors. Each names its skill, says when it applies, and tells Codex to read
SKILL.md with its file-read tool, which it must, because Codex does not inline
markdown imports. Functional, weaker than a mirror, and labelled as such at the
top of every one.

Codex is the most exercised of the three, for a reason that is not obvious from
the table: no per-code skill ships until Codex has run an adversarial pass over
it, reading the skill and running its scripts to try to falsify the benchmark.
Those passes found defects that construction and self-review did not, and they
ran from inside a clone with nothing linked into ~/.codex/skills.

How far to trust a skill

Every skill is built from the code's public source and its own manual, then made
to reproduce something. The evidence is stated rather than implied:

• Tier 1 (14 skills, including FRESCO, TALYS, CGMF, SMASH, SkyNet,
  Thermal-FIST): the code's own distribution ships reference values and the
  skill reproduces them, several byte for byte.
• Tier 2 (6 skills, including AZURE2, KSHELL, GiBUU, vHLLE): the code ships
  no reference output, so the skill is pinned by cross-platform reproduction,
  physics invariants such as the optical theorem, or an independent analytic
  solution. vHLLE is checked against closed-form Gubser flow rather than against
  its own output.

Most skills are built and verified on two platforms, macOS/ARM and
Linux/x86-64, and every one goes through an adversarial review pass by a second
AI before shipping. That pass is not ceremony. It has caught skills that
reported success while running a stale deck, test scripts whose checks had never
been shown to fire, and a test that fabricated its own input. What each pass
found is written down in each skill's references/verification.md.

A benchmark certifies that a build reproduces a known result. It does not
certify that your calculation is right. The physics is still yours.

Status

A working platform, in daily use by its author, released early to find out what
other people need from it. Things you may hit:

• The macOS and Linux binaries are unsigned, so the first run needs the
  quarantine attribute cleared. Windows is not built.
• Cold-start installs are under-tested. Every install path has been run once
  on a bare Linux box (thirteen clean, four stopping with a named missing
  dependency, three stopped by the harness rather than by the skill), and once on
  macOS only where the code was already present. Expect a missing dependency
  somewhere.
• TALYS wants about 11 GB of disk, 8.6 GB of it a structure database.
• The main README is available in English and Chinese. Skill documentation is
  currently English only.

Contributing

The most useful thing right now is a bug report about a skill that misbehaved,
especially a cold-start install failure, or any case where a skill produced a
plausible but wrong result. The second most useful is telling us which code
you wish had a skill.

To add one, read CLAUDE.md first. A code qualifies only if it is
publicly obtainable, builds from source on the target platform, and has a
published paper, and a skill ships only with an honest benchmark tier.

Licence and identity

MIT, see LICENSE, which also names the three things it cannot cover:
the physics codes themselves (you get those from their authors under their own
terms, several GPL and one non-commercial), the opencode fork in
fusion-core, and the third-party
papers summarised in kb-wiki/.

Built on opencode (MIT), so it runs on
whatever model you can reach, DeepSeek and Qwen and GLM as readily as Claude or
GPT. Not affiliated with the opencode project.

Palette, mark, and where each applies: BRAND.md.

Author

Jin Lei (金磊), Tongji University. [email protected]