Skyrim Forge Bridge 0.2.0

A safety-first local bridge that gives Grok Build, Claude Desktop, Claude Code, Codex, and other MCP clients structured Skyrim modding tools without granting them arbitrary binary writes or unrestricted shell access.

AI agent workstation

Version 0.2.0 adds a shared agent layer for Grok Build, Claude Code, Codex, Claude Desktop, and generic MCP clients.

For the easiest setup, double-click:

AI Agent Command Center.bat

The command center can:

• Install or repair all detected agent integrations.
• Register the local MCP server with Grok, Claude Code, and Codex.
• Build and officially validate a self-contained Claude Desktop .mcpb extension.
• Create new agent-ready Skyrim projects.
• Initialize existing mod projects without overwriting their instructions.
• Launch Grok, Claude, or Codex in a selected project.
• Run an agent and dependency doctor.
• Open the generalized prompt library.
• Open agent-ready Skyrim projects in Visual Studio Code when the code command is installed.

Direct helpers include:

• Install AI Agent Integrations.bat
• Build Claude Desktop Extension.bat
• Create New AI Skyrim Project.bat
• Initialize Existing Mod Project.bat
• Launch Grok for Skyrim.bat
• Launch Claude for Skyrim.bat
• Launch Codex for Skyrim.bat
• Agent Doctor.bat

See docs/AGENT_CLIENTS.md.

One-click Windows start

For normal use, double-click:

Skyrim Forge Bridge.bat

On the first run it automatically creates the private Python environment, installs the bridge, repairs the configuration when needed, and opens the GUI. Later launches simply open the application.

Optional helpers:

• Skyrim Forge Bridge.vbs launches silently after installation.
• Install or Update.bat reinstalls or updates the local environment.
• Repair and Launch.bat repairs the TOML configuration and launches the GUI.
• Create Desktop Shortcut.bat creates a desktop shortcut.
• Build Portable EXE.bat builds dist\\SkyrimForgeBridge.exe on Windows using PyInstaller.

The optional EXE contains the desktop GUI. Keep the normal installed project for MCP-server use with Claude or Codex.

What the bridge currently does

• Scans configured Skyrim, Vortex, MO2, and tools locations.
• Reads plugins.txt and reports enabled/disabled plugins.
• Inspects installed/unpacked mod directories.
• Inspects ZIP archives and optionally 7z/RAR archives through an allowlisted 7z.exe listing command.
• Detects broken archive roots, wrapper folders, bundled MO2 metadata, and suspicious absolute-path fragments.
• Reads the TES4 header of .esp, .esm, and .esl files without modifying them.
• Reports plugin masters, author, description, flags, size, and SHA-256.
• Validates constrained JSON patch plans and assigns risk/approval requirements.
• Creates isolated project workspaces with snapshots and append-only audit logs.
• Exposes the same functions as local MCP tools.
• Includes a small Tkinter desktop control panel.
• Detects Grok, Claude, Codex, Git, .NET, Node, and PowerShell.
• Bundles generalized Skyrim build, modernization, diagnosis, AIO, and compact prompts.
• Scaffolds shared AGENTS.md, CLAUDE.md, skills, commands, MCP config, and privacy-safe context files.
• Builds a standalone Claude Desktop MCPB extension on Windows.

What it deliberately does not do yet

• Write or binary-patch plugins.
• Compact FormIDs.
• Remove masters.
• Edit navmeshes, worldspaces, quests, or VMAD data.
• Launch or drive SSEEdit or Creation Kit.
• Execute arbitrary PowerShell, Python, Pascal, or shell code.
• Modify Vortex databases, MO2 metadata, installed mods, or the physical game Data directory.

Those are phase-two and later operations. They will require a typed Mutagen/Synthesis backend, transactional copies, semantic diffs, independent validation, and explicit approval.

Windows install

Open PowerShell in this folder:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

Then launch the desktop panel:

.\run-gui.ps1

Or run the CLI:

.\.venv\Scripts\skyrim-forge.exe scan

First setup

The installer creates:

%USERPROFILE%\.skyrim-forge-bridge\config.toml

Edit it manually or use the GUI. Point it at your real paths, for example:

tools_root = "S:\\Apps\\Skyrim Tools"
skyrim_data = "S:\\SteamLibrary\\steamapps\\common\\Skyrim Special Edition\\Data"
plugins_file = "C:\\Users\\YOU\\AppData\\Local\\Skyrim Special Edition\\plugins.txt"
workspace_root = "S:\\Skyrim Forge Workspaces"

MCP server

The server uses stdio, which is suitable for local desktop clients:

.\.venv\Scripts\skyrim-forge-mcp.exe

See docs/AGENT_CLIENTS.md for Grok, Claude Code, Claude Desktop, Codex, and generic MCP clients.

Safety model

All live inputs are read-only. Every generated project lives under workspace_root. Path traversal and symlink escapes are rejected. External processes are disabled by default. The only optional external process in this MVP is archive listing through a specifically configured 7z.exe.

Every operation is written to an append-only JSONL audit log.

Next engineering phase

The intended writer backend is a separately built and version-pinned C# helper using Mutagen. It will accept only validated patch-plan operations, write to transaction workspaces, emit semantic diffs, and refuse high-risk record families until dedicated validators exist.

See docs/ROADMAP.md.

Configuration repair

Version 0.1.1 accepts and automatically removes UTF-8 BOMs in config.toml. Malformed configuration files are backed up as config.toml.invalid-<timestamp>.bak, then replaced with safe defaults so the GUI can still open.

For an older 0.1.0 checkout, run:

.\repair-config.ps1

The 0.1.1 installer writes TOML using UTF-8 without a BOM on both Windows PowerShell 5.1 and PowerShell 7+.