# How to Use Universal Modder: Install, First Mod, Costs and Fixes

> Universal Modder is free, but its default fal sprite costs $0.211. Install it in Claude Code or Codex, mod an offline game you own, and fix common setup errors.

- Source: https://www.aifreeapi.com/en/posts/universal-modder
- Language: en
- Published: 2026-10-08
- Updated: 2026-10-08
- Publisher: AI Free API (https://www.aifreeapi.com)

Universal Modder is not a program you download and click through. It is a free, MIT-licensed bundle of Agent Skills (instruction files that teach a coding agent a workflow; nothing to do with player skill), a Python command-line tool called `um`, a config for fal's asset-generation server, and a shared knowledge base describing how other people modded specific games. You use it by talking to a coding agent such as Claude Code or Codex. The agent scans your game, writes the mod, generates art through fal and tests the result in the running game.

The shortest working path looks like this. Install the plugin in the agent you already pay for. Install Git, Python 3.10+ and ffmpeg. Set a `FAL_KEY` if you want generated art. Then open an empty folder and ask `/universal-modder:mod-any-game` for one small feature in a single-player game you own that already has a mod loader; Terraria with tModLoader is the easiest first target. You are done when you have seen the feature work in the actual game, not when the agent reports that the code compiles.

Three facts decide whether that path works for you, so check them before installing:

- The in-game automation (launching, clicking, screenshots, recording) only runs on Windows or WSL.
- The agent refuses online games protected by anti-cheat, and games you don't own.
- The toolkit is free, but the art is not: the default sprite command costs $0.211 per image on fal as of October 8, 2026.

The GitHub repository was created on September 30, 2026 and had about 5,400 stars by October 8. It is still young: the version string is 0.2.0, there are no formal releases, and the skill files change almost daily. Treat the [install table in the README](https://github.com/rehan-remade/universal-modder#install) as the source of truth for commands.

## Check four things before you install Universal Modder

| Check | Good to go | Stop or change plan |
| --- | --- | --- |
| Coding agent | Claude Code on a paid Claude plan or Console API billing, Codex, Cursor, VS Code with Copilot, or OpenCode | Gemini CLI on a personal Google login, which lost access on June 18, 2026 |
| Operating system | Windows 10/11, or WSL on Windows | macOS or Linux: recon, art and code work, but `um win` will not launch, click or record the game |
| Game | You own it, you play it single-player or on a server you host, and it has a mature loader (tModLoader, SMAPI, BepInEx, Fabric) | Online clients protected by EasyAntiCheat, BattlEye, Vanguard, Ricochet, ACE or VAC on official servers; anything you don't own |
| Budget | A Claude or ChatGPT plan you are willing to spend on long sessions, plus a few dollars of fal credit | No fal key: use local ComfyUI through `um comfy`, or stay with placeholder art |

### Which coding agent to use with Universal Modder

Use the agent you already pay for. The skills are identical across agents, so the choice is mostly about cost and limits.

- **Claude Code** has the best-documented route: a plugin install plus a named skill you can call directly. You need a paid Claude plan or a Console account with API billing. Plugins only load in local sessions; a cloud session such as claude.ai/code does not load them, according to the [Claude Code plugin docs](https://code.claude.com/docs/en/plugins). Long modding sessions eat plan limits, so read [Claude Code Pricing: Pro vs Max and When the Upgrade Pays Off](/en/posts/claude-code-pricing-pro-vs-max) before a big project.
- **Codex** gets the same skills through its own plugin command and runs under your ChatGPT plan limits or an API provider. It will ask permission before running commands on your PC; [Codex Sandbox and config.toml: Permissions Without Full Access](/en/posts/codex-config-toml) explains how to loosen that without handing over full access.
- **Gemini CLI** is still listed in the README, but since June 18, 2026 Google's "Login with Google" no longer reaches Gemini CLI for Gemini Code Assist for individuals, Google AI Pro or Google AI Ultra ([Google's deprecation notice](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals)). Standard and Enterprise subscriptions are unaffected. Pick this route only if your Gemini CLI sign-in still works; [Gemini CLI Consumer Access Ended: What Still Works and How to Migrate](/en/posts/gemini-cli-deprecated) covers the alternatives.
- **Local models**: asked about LM Studio Bionic, the maintainer said it "should mostly work" but hasn't been tested. The tested local route is OpenCode pointed at LM Studio's local server, and the maintainer adds that the model matters ([issue #126](https://github.com/rehan-remade/universal-modder/issues/126)).

If you are torn between the two main options, [Claude Code vs Codex in 2026: Which Coding Agent Should You Use Now?](/en/posts/claude-code-vs-codex) compares them on general coding work.

### Universal Modder on Windows, WSL, macOS and Linux

Windows is the full experience. The `um win` commands that launch the game, take screenshots, send input and record the window check the platform first and exit unless they are running on native Windows or WSL. On Linux and macOS they point the agent at system tools instead (xdotool or screencapture plus ffmpeg), so expect to launch and check the game yourself more often.

Everything else is plain Python and works anywhere: `um scan`, the knowledge base, `um fal` and the sprite tools. Mac modding is possible; one field note in the knowledge base documents a Halo Trial mod made on macOS through Wine. Just don't expect the hands-off test loop you see in the videos.

### Games to avoid for a first Universal Modder project

The agent stops, by design, on these:

- Online games with kernel or user-mode anti-cheat: EasyAntiCheat, BattlEye, Vanguard, Ricochet, ACE, EA Javelin, nProtect, XIGNCODE, mhyprot, and VAC on official servers. It will offer an official offline mode, a private server you run, or official tools such as Steam Workshop or a map editor instead.
- Anything that needs DRM, anti-cheat or an ownership check bypassed.
- Games you don't own. It won't download games, ROMs or disc images.

For a first project, pick a game with a mature community loader: Terraria (tModLoader), Stardew Valley (SMAPI), Minecraft (Fabric) or a Unity game with BepInEx. Then look up prior work. Run `um kb search "<game>"` or browse the [knowledge base index](https://github.com/rehan-remade/universal-modder/blob/main/knowledge/INDEX.md), which held 78 game notes and 50 technique notes on October 8, 2026. Each note records the exact versions that worked, the route, how it was verified and the gotchas. A note marked "in-progress", or written for a different game version, is a starting point rather than a promise.

## Install Universal Modder in Claude Code, Codex or another agent

First install the prerequisites: Git, Python 3.10 or later and ffmpeg. `uv` is recommended, and Blender is only needed if you want 3D models rendered into sprites. On Windows, winget handles all of them:

```powershell
winget install --id Git.Git -e
winget install Python.Python.3.12
winget install astral-sh.uv
winget install Gyan.FFmpeg
```

Close the terminal, open a new one, and confirm each tool answers: `git --version`, `python --version`, `uv --version`, `ffmpeg -version`.

Then install the toolkit for your agent. These are the README's commands as of October 8, 2026:

| Agent | Install |
| --- | --- |
| Claude Code (inside a session) | `/plugin marketplace add rehan-remade/universal-modder`, then `/plugin install universal-modder@universal-modder` |
| Codex | `codex plugin marketplace add rehan-remade/universal-modder`, then `codex plugin add universal-modder@universal-modder` |
| Gemini CLI | `gemini extensions install https://github.com/rehan-remade/universal-modder` |
| VS Code / Copilot | Enable `chat.plugins.enabled`, run **Chat: Install Plugin From Source**, enter the repo URL |
| Cursor | Cursor Marketplace, or clone the repo |
| OpenCode | Clone the repo and run `opencode` inside it |
| Any Agent Skills agent | `npx skills add https://github.com/rehan-remade/universal-modder` |
| Anything else | `git clone https://github.com/rehan-remade/universal-modder` and start your agent inside the folder |

In Claude Code, choose the User scope when asked so the plugin works in every folder, and run `/reload-plugins` if Claude Code says the components need reloading. Plugin installs and clones put `um` on your PATH. For a skills-only install, add the CLI separately:

```bash
uv tool install git+https://github.com/rehan-remade/universal-modder
```

### Set FAL_KEY for sprites, sound and 3D

Create a key on the [fal dashboard](https://fal.ai/dashboard/keys) and add some credit. Then expose it as an environment variable:

```powershell
# Windows: saved for new terminals, so reopen the terminal afterwards
setx FAL_KEY your_key
```

```bash
# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc
export FAL_KEY=your_key
```

`um` can also read the key from a `.env` file in your project folder, but the fal MCP server that the agent talks to reads only the environment variable. Set the variable and you avoid half-working setups. Without any key, `um comfy` generates images from a local ComfyUI server instead.

### Confirm Universal Modder loaded

Run three quick checks before your first real request:

1. In Claude Code, open `/plugin` and confirm universal-modder appears among your installed plugins. In other agents, ask "which skills do you have?" and look for `mod-any-game`.
2. In a terminal, `um --help` should list command groups such as `scan`, `fal`, `sprite`, `win`, `backup` and `kb`.
3. `um kb search terraria` should return field notes, and `um scan --list` should list games from your Steam, Epic or Xbox libraries.

If step 3 crashes on Windows or shows no Steam games, jump to the [fixes table](#universal-modder-setup-errors-and-fixes).

## Make your first mod with Universal Modder: a Terraria walkthrough

Terraria is the gentlest first target. It has no anti-cheat, tModLoader is free on Steam, and the knowledge base already holds working Terraria notes, including the project's own *Fal Arsenal* example. The steps carry over to other loader-based games; only the tools change.

1. **Prepare the game.** Own Terraria on Steam, add the free tModLoader app to your Steam library, launch tModLoader once so it creates its folders, then close it. tModLoader refuses to start without the Steam library entry, and the agent will not patch that check.
2. **Open an empty project folder**, for example `C:\mods\terraria-boomerang`, and start your agent there. The agent keeps its code, assets and journal in this folder.
3. **Ask for one small feature.** In Claude Code, call the skill by name so its workflow definitely runs:

   ```text
   /universal-modder:mod-any-game Add one boomerang to the Steam version of Terraria that bounces between up to four enemies before returning. Use placeholder art for now. Done = I see it working in game. No showcase video.
   ```

   In Codex and other agents, write the same request in plain language and mention the `mod-any-game` skill.
4. **Answer the intake questions.** The agent confirms the game, the store, the idea in one sentence, what counts as done, and whether anything online is involved. It starts a `MODLOG.md` journal that records paths, file formats, what failed and what comes next.
5. **Let it run recon.** Expect `um kb search "terraria"` and `um scan "Terraria"`. The scan reports the engine and version, managed or native code, anti-cheat, installed loaders, save folders and ranked routes. The agent then picks the cheapest route that reaches your idea, which for Terraria is tModLoader's API.
6. **Approve the safety net.** Before the first modded launch it runs `um backup create` on the saves folder `um scan` reported, with `--name terraria-saves`, sets up a separate lab save folder with tModLoader's `-tmlsavedirectory`, and switches the game to windowed mode so screenshots and clicks stay stable. Your real characters and worlds stay untouched.
7. **Watch the vertical slice.** It builds that one item end to end with placeholder art, launches the game, and checks tModLoader's `client.log` plus a screenshot. It asks before taking over your mouse and keyboard, installing anything into the game folder, changing registry or graphics settings, deleting files, or publishing. Once you say yes to input automation, leave the PC alone; stray clicks throw off its coordinates.
8. **Check it yourself.** Load into the lab world and use the boomerang. That is the finish line.

![Four numbered rows for a first Universal Modder mod: intake with MODLOG.md, recon with um scan, a safety net with um backup create, and a slice checked in client.log, plus the actions the agent asks permission for](https://www.aifreeapi.com/posts/en/universal-modder/img/first-mod-loop.webp)

If the same failure repeats three times, the skill's circuit breaker stops the agent and has it write down what it knows. Take that as the signal to change the route, shrink the idea, or check the knowledge base for a known gotcha. Don't just tell it to try again.

With the slice working, widen in small steps: ask for real sprites (check the price first, see below), then the next item. For a project that runs across several days, start a new session in the same folder and say "Read MODLOG.md and continue."

To share the result, the agent runs `um publish check <mod> --game "<install path>"`, which blocks game files, decompiled code and leaked keys from going out. It then writes a README with install steps and credits. Say plainly that the mod was built with AI. If you want, it can also turn `MODLOG.md` into a field note for the knowledge base and open a pull request, but only after you say OK.

## How much Universal Modder costs: fal prices and a worked example

The toolkit itself is free. You pay two separate bills: your coding agent's plan or API usage, and fal for any generated assets. These are the default fal models behind each `um fal` command and fal's listed prices as of October 8, 2026:

| Command | Default fal model | fal price |
| --- | --- | --- |
| `um fal sprite` | [GPT Image 2](https://fal.ai/models/openai/gpt-image-2), transparent background, high quality, 1024×1024 | $0.211 per image (medium $0.053, low $0.006) |
| `um fal image` | [Nano Banana 2](https://fal.ai/models/fal-ai/nano-banana-2) at 1K | $0.08 per image (2K ×1.5, 4K ×2) |
| `um fal rmbg` | [BiRefNet v2](https://fal.ai/models/fal-ai/birefnet/v2) background removal | listed at $0 per compute second |
| `um fal sfx` | [ElevenLabs sound effects v2](https://fal.ai/models/fal-ai/elevenlabs/sound-effects/v2) | $0.002 per second |
| `um fal model3d` | [Trellis 2](https://fal.ai/models/fal-ai/trellis-2) image-to-3D at fal's default 1024p | $0.30 per model (512p $0.25, 1536p $0.35); run `um fal price fal-ai/trellis-2` before a batch |

The defaults come from the toolkit's [`um/fal.py`](https://github.com/rehan-remade/universal-modder/blob/main/um/fal.py). The detail that matters most is that `um fal sprite` uses GPT Image 2 at **high** quality unless told otherwise.

A worked example, for assets only:

- 10 sprites at the default: 10 × $0.211 = **$2.11**
- the same 10 with `--quality medium`: 10 × $0.053 = **$0.53**
- the same 10 with `--quality low`: 10 × $0.006 = **$0.06**
- 10 Nano Banana 2 images at 1K: 10 × $0.08 = **$0.80**
- 30 seconds of sound effects in total: 30 × $0.002 = **$0.06**

Treat these as an example, not a quote. Rerolls multiply them, and 3D models and video cost more. fal notes that its prices can change. Two habits keep the bill predictable. Tell the agent to use `--quality medium` for sprites that will be shrunk to a few dozen pixels anyway, and ask it to run `um fal price <endpoint>` before any 3D, music or video generation. Every call is logged to `fal_manifest.jsonl`, so you can see afterwards what was generated. If transparent sprites come back with a fake checkerboard or halo edges, [GPT Image 2: Generate and Validate Transparent PNG or WebP](/en/posts/gpt-image-2-transparent-background) shows how to check the alpha channel.

![Example cost of 10 um fal sprite images on fal: 10 × $0.211 = $2.11 at the default high quality, $0.53 at medium and $0.06 at low, with proportional bars](https://www.aifreeapi.com/posts/en/universal-modder/img/fal-sprite-cost.webp)

The agent's own cost has no fixed number per mod, and there is no published measurement of tokens used per modding session. Recon, decompiling and repeated test launches are long, tool-heavy sessions, so expect them to use a noticeable share of plan limits. In Claude Code, an enabled plugin's skill names and descriptions also sit in context on every turn, even when you are not modding. Disable it with `/plugin` or `claude plugin disable` between projects. If Codex stops mid-session with a 429, see [Codex 429 After Retries: Find the Limit That Owns the Request](/en/posts/codex-rate-limits).

If you can't buy a Claude or ChatGPT plan where you live, Codex can also run through a pay-per-token provider. For example, laozhang.ai documents a [Codex CLI setup](https://docs.laozhang.ai/scenarios/programming/codex-cli) that uses a custom provider in `config.toml`. You pay per token, there is no published figure for what a modding session costs that way, and how well its models handle reverse engineering is untested. That route serves OpenAI-style models for Codex; it is not a way to run Claude. [Connect Codex to a Third-Party Model API Without Guessing the Protocol](/en/posts/codex-third-party-api) walks through the general setup.

## Universal Modder setup errors and fixes

| Symptom | Cause | Fix |
| --- | --- | --- |
| `um kb search` crashes on Windows with `UnicodeEncodeError: 'charmap' codec can't encode character` | The console uses the legacy cp1252 encoding and some field notes contain other characters ([issue #152](https://github.com/rehan-remade/universal-modder/issues/152), open as of October 8) | In PowerShell, run `$env:PYTHONUTF8 = "1"` before `um kb`, or set it permanently |
| Install fails with `Failed to clone Git repository ... Error: spawn git ENOENT` | Git is missing or not on PATH ([issue #109](https://github.com/rehan-remade/universal-modder/issues/109), seen with Gemini CLI on Windows) | `winget install --id Git.Git -e`, reopen the terminal, check `git --version`, retry |
| `gemini` won't run in PowerShell | PowerShell blocks `gemini.ps1` when script execution is disabled, which is the Windows default | Type `gemini.cmd` instead of `gemini` |
| `claude plugin update` says "already at the latest version (0.2.0)" and fixes never arrive | Until October 6, 2026 the plugin manifest pinned version 0.2.0, so earlier installs stayed on the cached copy ([PR #108](https://github.com/rehan-remade/universal-modder/pull/108)) | Uninstall the plugin from `/plugin` and install it again once; later updates track new commits |
| `um scan --list` shows no Steam games | Older versions only looked in Program Files and missed Steam installed in places like `C:\Steam` or `D:\Steam` (fixed October 6, [PR #95](https://github.com/rehan-remade/universal-modder/pull/95)) | Reinstall the plugin, or rerun the `uv tool install` command with `--reinstall` |
| Agent's fal tools say the key is missing even though `.env` has it | The fal MCP server reads only the `FAL_KEY` environment variable | Set `FAL_KEY` as a real environment variable and restart the agent |
| `um win` exits saying it drives Windows games | You are on macOS or Linux | Run on Windows or WSL, or launch and test the game yourself |
| tModLoader won't launch | The free tModLoader app isn't in your Steam library | Add it to your library; the agent will never patch the check |
| Agent stops after three identical failures | The skill's circuit breaker | Read `MODLOG.md`, then change the route or narrow the idea |

## What Universal Modder adds over just asking Claude Code or Codex to mod

A capable agent can mod some games without the plugin. A Japanese YouTube creator reported that Claude Code completed 8 of 8 modding tasks across three games without the toolkit's skills ever being called, working directly through shell commands. That is one creator's small test, with games and versions not stated. It does suggest the skills are not what makes modding possible; they shape how the agent goes about it.

The plugin earns its context cost when you want the parts an improvising agent tends to skip:

- **A safety routine**: saves backed up before the first modded launch, a separate lab profile, approvals before input automation or game-folder changes, and kills by exact process ID.
- **Tools the agent would otherwise rebuild**: `um scan` for engine, anti-cheat and save folders; `um fal` with a manifest of every generation; `um sprite` and `um render3d` to fit art to the engine; `um win` for game-only input and recording; `um publish check` before sharing.
- **Prior art**: field notes from earlier sessions, so the agent starts from versions and routes that already worked instead of rediscovering the same traps.
- **A finish line**: a mod counts as working when it is seen working in the game, not when it compiles.

To make sure that workflow actually runs, call `/universal-modder:mod-any-game` explicitly instead of hoping a plain request triggers it.

## What Universal Modder refuses to do, and is modding legal?

Universal Modder's [safety rules](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/references/safety.md) are fixed. The agent won't break them even if you ask:

- no injection into online clients protected by anti-cheat, and no aimbots, ESP, speed hacks or other multiplayer cheats;
- no bypassing anti-cheat, DRM (Denuvo, Steam stub) or ownership checks; if a game needs anti-cheat off for mods, it uses only the official offline launch option;
- no downloading games, ROMs or disc images;
- no shipping game files, extracted assets or decompiled code; mods ship as your code, your assets, and patches or converters that run on the player's own install;
- backups before touching saves, and your OK before input automation, loader installs, deletions or publishing.

Whether a particular mod is legal has no single answer. It depends on the game's EULA and the publisher's mod policy, so search "<publisher> mod policy" before you publish anything. The risk concentrates where those rules point: redistributing game code or assets, cheating against other players, bypassing protection, and making money. Takedowns have happened even without assets. Take-Two had the reverse-engineered GTA III and Vice City projects (re3 and reVC) removed from GitHub and sued their authors in 2021, and Activision sent the H2M mod a cease-and-desist in 2024. fal output is yours to use under fal's terms, but check each model's license before any commercial use.

Expect a mixed reception, too. Some modding communities, including certain recompilation Discords, ban AI-built projects, and the repo has an open issue titled "Please limit this thing." Disclose AI use up front.

Get the toolkit only from the [GitHub repository](https://github.com/rehan-remade/universal-modder). universal-modder.org is a community hub built on the open-source project, and the README doesn't name it as the project's site. The README's own mod hub is listed as "coming next." The safety notes warn that a viral mod's "download" is often malware, and any plugin you install runs code with your user privileges.

## Universal Modder FAQ

### Is Universal Modder free?

Yes. The toolkit is MIT-licensed and free to install. What costs money is the coding agent (a Claude or ChatGPT plan, or API usage) and any fal generations, starting at $0.211 per default sprite as of October 8, 2026. Local ComfyUI art through `um comfy` avoids the fal bill.

### Does Universal Modder work on a Mac?

Partly. Recon, the knowledge base, fal assets and code work on macOS, but `um win` (launch, input, screenshots, recording) runs only on Windows or WSL. On a Mac you test in the game yourself, and many Windows games will need Wine or similar.

### Can I use Universal Modder without a fal API key?

Yes. The agent can still scan, write code and test with placeholder art, and `um comfy` makes images from a local ComfyUI server without a key. You lose fal's sprites, sound effects, voice, music and image-to-3D.

### Does Universal Modder work with LM Studio or other local models?

Possibly, with a capable model. The tested local route is OpenCode connected to LM Studio's local server; LM Studio Bionic is untested, and the maintainer warns that the model matters. Try a small, well-documented game first to see whether your model keeps up.

### Can Universal Modder merge two games, like Minecraft inside GTA V?

Yes, that is what the `mashup-mods` skill covers, and the repo includes a working Minecraft × GTA V story-mode example. Mashups are far harder than a single item, so make one small mod first and check the knowledge base for both games before you ask.

### Where can I download mods made with Universal Modder?

The project's own mod hub isn't live yet. The repo's examples are source code you build against your own install, not ready-made downloads. Community sites exist, but treat any "download" of a viral AI mod with suspicion and install loaders only from their official repositories.