Repository navigation
v4.1.0 — X4 AI Assistant Toolkit
v4.1.0 of the X4 AI Assistant Toolkit keeps your derived data current without you asking, adds new ways to see where a value or a saved variable comes from, and tightens what the guards watch. Released 2026-11-05 (the CHANGELOG heading reads 2026-11-04).
Claude Code and Codex remain the first-class integrations. OpenCode is best effort. The guards read known command forms; they are not a sandbox.
What changes for you
Your saves and profile
- Save sentinel. After every tool call it reports any save that was modified or removed with no backup taken first, whatever changed it, including scripts the pre-call guard cannot read. It never blocks. It guards against accidents and careless scripts, not a determined attacker.
- Save locks cannot be turned on in this version.
save-lock onandsetup.sh --save-lockrefuse and change nothing. A lock also binds X4 itself, so you could not save over a locked save, and Windows permissions cannot tell X4 and agents apart. If you hold locks from an earlier development build (not a public release),python tools/agent-harness.py save-lock status|off|unlockstill work;offandunlockneed an elevated prompt. Saves stay protected by the guards, the backup taken before a save is changed, and the sentinel. - Agents ask before every game launch or restart they start, naming the game, mode, desktop and test profile or save. Earlier approvals and "continue" do not count.
- Fewer repeat prompts for the mod list. Editing the profile's root
content.xml(enabling or disabling a mod you asked to install) no longer asks a second time. Deleting it, other profile files and saves still ask. A move ontocontent.xmlstill asks, because it also removes its source. - Deleting a deployed mod asks once per command, naming every mod the command touches. Deleting the install itself or
extensions/wholesale, andreference/, stay blocked. - A typed file deletion of a deployed mod folder or ordinary XML now asks instead of being rejected as a direct edit of the deployed copy. Direct writes, write-only batches, explicit moves, archive protections, save preservation and whole-install/reference blocks keep their prior policy.
- Guards read more indirect commands: deletes or writes handed to another program such as
watch,wsl,tmux,sshto this machine and similar runners, and creating a junction or link into a protected folder is refused. A list of runners cannot be complete; see the limits below. - Codex: a profile XML edit the guard asks about can be approved once with a printed
PROFILE_EDIT_APPROVAL <digest>line (24-hour expiry, used once, refused if the file changed). Details are indocs/profile-edit-approval.mdin the repository and the release zip.
Keeping derived data current
x4freshprints one verdict per derived store (effective store, xref index, BaseXx4rawandx4eff): FRESH, STALE, UNKNOWN, MISSING, REBUILDING or NOT-BUILT, plus what the last build could not include.x4fresh rebuildrebuilds what is not fresh;x4fresh acceptrecords losses you understand so they stop repeating.- Background rebuild at session start (Claude Code and Codex) for the effective store and xref index. It waits while X4 is running. The BaseX databases are only reported, never rebuilt unattended. To stop it, set
X4_FRESH_AUTO=off. - A mod edited while a build runs no longer reads FRESH afterwards.
Investigating mods and saves
x4effective dump <vpath> --annotatemarks every node an overlay changed with a comment naming the mod, op and patch line, and lists removals. It reports who won each node, not who introduced it; after a whole-file replace no node is annotated. (#15)x4save vars <pattern> [save]lists named variables matching a regex, such as MD cue variables, with where each lives. Tables, lists and groups are shown astable#<id>,list#<id>andgroup#<id>and are not expanded or searched. A no-match result names what was not searched. Only gzipped*.xml.gzsaves are read. (#16)x4effective find TEXTlooks entities up by the name the player reads.x4effective dumpon a bare path to a file only a DLC ships now returns the document mods actually patch, with a note. It used to return the unpatched file with no warning (588 of 716 patched DLC documents on the development machine).x4diffnow compares each mod'scontent.xml, and--fileaccepts./path, backslashes and absolute paths. It used to say "no differences" for a manifest whose version had changed.x4modlist downloads DIR...reads manifests inside downloaded.zip,.7zand.rarfiles without extracting them and compares them with what is installed. It also warns about a profile entry turning an id off, a same-name mod under a different id, a test profile that would load the mod, and merged icon totals past what one install was measured to load..7zand.rarneed 7-Zip. It exits 3 when any archive was unreadable.x4modlist refresh --dry-runshows which rows a refresh would fetch, search for or skip, with no network, key or write.- Experimental:
x4similar --geometryand--geometry-auditcompare ship render surfaces. Real-hull thresholds and runtime poses are not qualified. Needs the optionalgeometryextra (seetools/x4validate/docs/GEOMETRY.md).
Disk housekeeping
- Retention follows a certainty rule. Age, size and file names only trigger a review. Housekeeping retires a payload only when it re-proves an identical retained copy or you declare those exact bytes obsolete.
- Rebuildable BaseX caches are now deleted permanently, with no backup and no Recycle Bin copy. This reverses v4.0.0 for these caches only. Everything else housekeeping removes still goes to the Recycle Bin or stays.
- Optional cold backup vault and task archiving in
x4housekeep(off unless configured in your privatex4-housekeep.json). - The session-start note warns when the Recycle Bin is large (default over 10 GiB).
Working across sessions
- Session charter and ledger: a session's first prompt is recorded as its origin, and agreed work is tracked in a ledger that is shown at every session start.
find-sessionskill finds the past Claude Code or Codex session where something was discussed. It needs obra/episodic-memory installed separately.
If you make mods
x4-mod-release-reviewnow ends with the whole upload pack in one folder, andscripts/verify-mod-pack.pyrefuses a pack with a missing or empty file,<br, an HTML entity, CRLF, a header line in a paste file, a changelog line over 120 characters, or an archive that differs from the manifest.
Fixes
x4save vars | headandx4effective ... | headend quietly when the reader closes the pipe, instead of reporting a broken save or a traceback.- Save sentinel: a save that vanishes mid-scan is the only one reported lost; a record locked by another session no longer causes a false "record lost" alarm; a denied save folder no longer stops every look.
x4housekeepno longer treats an unreadable live-work source as "no live work".- The test suite now passes on an installed toolkit.
- Upgrade previews report why they failed and exit 2, and a default apply no longer creates a config the install never had.
Upgrading to 4.1.0
- Rerun the installer with
--over-existing(-OverExistingin PowerShell). Local notes,x4-paths.envand.claude/settings.local.jsonstay in place. If you edited.claude/settings.json, use the reviewedupgrade-stage/upgrade-applyworkflow in ADAPTING.md. - The effective store and BaseX
x4effread STALE until rebuilt once. Session start rebuilds the store and xref index; rebuild BaseX yourself withx4fresh rebuild. - The first rebuild reports known losses and
x4fresh statusexits 3 until you runx4fresh acceptonce. Nothing failed: truncated property subtrees are now listed by name. - If you use
x4housekeep: runpython scripts/x4housekeep.py versionand record the new digest inapproved_sha256. The hold on folders with a running job now applies only ifjob_ledgernames a resource-job ledger. - Upgrading from 3.x: read the 4.0 upgrade notes first (config location, edited
CLAUDE.md).
Known limits
- The guards judge a shell command by how its path is written. A write through an existing link, Windows admin-share and Cygwin spellings, and programs that run a command string inside themselves (
awksystem(),os.system,find -exec bash -c,docker,systemd-runand others) are not read. The full list is in the "Known gaps" section of the CHANGELOG. - The sentinel decides "the game wrote this" from two signs and cannot separate writers inside that window. The signs were measured from file stamps; no game session was run.
- No CI timing exists yet for the fix to the slow 3,589-path file check (BLIND-SPOTS F340).
- The elevated
save-lock unlockwas not run end to end for this release. - Closed-pipe handling covers
x4effectiveandx4saveonly; 10 of the other console tools still exit 120 for--helpinto a closed pipe. - Windows is the primary environment. OpenCode does not run a session-start hook, so it has no background rebuild.
Full details and evidence: CHANGELOG.
Independent fan project. No Egosoft game data, AI model or subscription is bundled.
Validation and release asset
- CI: run 41992260237 on
03135fd9, all 14 jobs green on attempt 2. Attempt 1 failed one parser test on a PowerShell translation timeout and the cold-archive leg on a runner disk quota; both passed when re-run on the same commit, so both are recorded here as intermittent, not as a clean first pass. Tests: Ubuntu 7,501 passed, 418 skipped; Windows 7,943 passed, 64 skipped; installed copy 6,522 passed, 891 skipped; cold archive 7,287 passed, 486 skipped; 0 failed in each. - Tag:
v4.1.0at03135fd92b3afbc7430861abe2e419a15852515d - Archive:
X4.Foundations.AI.Assistant.Toolkit-v4.1.0.zip, size 11,455,570 bytes, SHA-256facbd602b6a3894ad2b5a778445db3cb6a7db24419ea9154911427edc8224c1c