How to install and use Universal Modder

Requirements

Install the prerequisites in one go

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # optional, for 3D → sprites

brew install git python ffmpeg uv
brew install --cask blender                 # optional

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows, macOS and Linux: what works where

Most of the toolkit is cross-platform. The part that drives a running game (launch, screenshot, input, window recording with game-only audio) is Windows-first, because that's where the games are. Agents can drive Windows games natively or from WSL2.

On macOS and Linux the agent can still test in game with the OS's own capture tools (screencapture, ffmpeg, xdotool), but nothing is pre-wired. Field notes such as running xEdit under Linux or HL2 under Wine on macOS show it's possible.

Install by agent: side-by-side

Every route installs the same skills (Agent Skills format), the fal MCP server and the um CLI.

Claude Code

Run inside a Claude Code session (not your shell):

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

Choose user scope so it's available in every folder, then run /reload-plugins if prompted. The full walkthrough, including Claude Desktop and how to call each skill, is on the Universal Modder + Claude Code page.

OpenAI Codex

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Codex reads the skills from .agents/skills and the MCP config from .codex/config.toml.

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

The extension manifest is gemini-extension.json; instructions come from GEMINI.md, which points to AGENTS.md.

VS Code with GitHub Copilot

1. Open Settings and enable chat.plugins.enabled.
2. Open the Command Palette and run Chat: Install Plugin From Source.
3. Paste https://github.com/rehan-remade/universal-modder.

MCP config lives in .vscode/mcp.json.

Cursor

Install from the Cursor Marketplace, or clone the repo and open it: Cursor reads AGENTS.md and .cursor/mcp.json automatically.

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

opencode.json adds the skills and the fal MCP server.

Any other agent

# skills only, into your agent's skills folder
npx skills add https://github.com/rehan-remade/universal-modder

# or the whole thing: start your agent inside the clone
git clone https://github.com/rehan-remade/universal-modder

Install the um CLI on its own

Plugin installs and clones already put um on PATH. If you use the skills somewhere else, or want um in a normal terminal, install it as a tool. It installs from GitHub; it is not on PyPI, so pip install universal-modder won't work.

uv tool install git+https://github.com/rehan-remade/universal-modder
# or
pipx install git+https://github.com/rehan-remade/universal-modder

Every command group has --help with examples. See the um CLI reference.

Set your fal API key

Get a key at fal.ai/dashboard/keys (you'll need to add credit; it's shown only once, so save it). It powers both the fal MCP server and um fal.

export FAL_KEY="your-key"
# make it permanent
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # or ~/.bashrc

setx FAL_KEY "your-key"
# then open a new terminal and restart your agent

No key? um comfy makes images with a local ComfyUI server instead. Audio, 3D and video still need fal. Prices are on the cost page.

Check the install

um --help
um kb search "terraria"       # prior field notes (works outside the repo too)
um scan --list                # games found on this machine
um fal price fal-ai/trellis-2 # confirms FAL_KEY works

Your first session: one small, reversible change

1. Pick an easy gameGames with a popular loader are the gentlest start: Terraria (tModLoader), Stardew Valley (SMAPI), Minecraft (Fabric/Forge), Unity games with BepInEx, Unreal games with UE4SS. See the game library.
2. Ask for recon first
   promptCopy

   What engine is my copy of Terraria, has anyone modded it before (search the knowledge base), and what route would you take? Don't change anything yet.

3. Let it back up and set up a labThe agent snapshots saves with um backup create, uses a separate profile or world, and asks before installing a loader.
4. Build one slice
   promptCopy

   Add one boomerang that bounces between enemies four times before returning. Placeholder sprite first, then a fal sprite once it works in game.

5. Verify, then expandLaunch the game, look at it, and only then ask for more. Long projects live in MODLOG.md; tell a fresh session to “read MODLOG.md and continue”.

Troubleshooting

The marketplace add fails with a Git / SSH error

Plugin marketplaces are cloned with Git. If your machine has no GitHub SSH key, tell Git to use HTTPS for GitHub:

git config --global url."https://github.com/".insteadOf [email protected]:

Skills don't show up after installing

Run /reload-plugins (Claude Code) or restart the agent. Check the plugin is enabled in /plugin.

um: command not found

Open a new terminal after the plugin install, or install the CLI with uv tool install as above and make sure ~/.local/bin is on PATH (uv tool update-shell).

um fal says the key is missing

FAL_KEY must be set in the environment the agent was started from. Restart the agent after setx or editing your shell profile.

um win refuses to run

It drives Windows games only, from Windows or WSL2. On macOS/Linux, test in game manually.