X4 Claude Code Modding Toolkit

GitHub Repository

What Is This?

Claude Code is an AI assistant by Anthropic that runs directly on your computer. Unlike ChatGPT or a regular Claude chat, it can read your files, run commands, edit configs and execute scripts -- all with your permission. Think of it as a modding expert sitting next to you who can actually touch your files.

X4 modding is full of silent failure modes. A diff patch whose sel= matches nothing validates clean, loads clean, and does nothing. A multi-file change forgets one file and the ware never appears. Another mod quietly overwrites the value you just set. None of it crashes; it just doesn't work, and you find out an hour into a playthrough.

Most people who try to use an AI assistant for modding spend days wiring up tools, explaining the engine, and building guardrails so it doesn't wreck their install. This toolkit ships with all of that already solved -- plus a suite of X4-specific tools, written for this environment, that answer questions no off-the-shelf tool can.

New in v2. 7 -- the tools tell you WHICH mod moved

Every tool here refuses to answer from stale data rather than hand you a confidently wrong number. That was the right behaviour and it was exasperating: it told you the world had changed, never what changed. Localising a single updated mod took nine investigative steps.

x4modlist changed now answers it directly, and x4modlist snapshot gives you a baseline to compare against.

Two things it can now see that it genuinely could not before. A mod whose files changed while its content.xml stayed put -- which is the ordinary "edit the file, copy it in" workflow -- was completely invisible: measured on a real 121-mod list, 72 of them had at least one file newer than their own manifest, and every tool reported FRESH while describing a different set of mods. That failed in the unsafe direction. So did a mod enabled or disabled in the game's own mod menu, because toggling rewrites only the profile manifest.

Also in this release: a stale-data warning that named a command the release did not actually ship (it ships now); stale warnings that show both fingerprints, so "how far did it move?" is answerable without writing a script; and a set of fixes to the toolkit's own self-check -- the one that deliberately breaks the code to confirm the tests notice. It could not restore the tree if it was killed mid-run, and it silently measured a narrower scope than it reported. While it runs