Skip to content
Universal Modder Guides

install / codex

How to install the Universal Modder Codex plugin

Quick answer

Install universal-modder in Codex with two CLI plugin commands, then run the modding skill on a PC game you own in about five minutes. The plugin is free; using Codex may require an active model subscription or API credits, and fal asset generation is a separate paid service.

Prerequisites

  • A single-player PC game you legally own, within the usage boundary below.
  • Codex installed and configured with working CLI access.
  • Python 3.10+ and ffmpeg installed; uv is recommended.
  • A separate mod working folder on your system.
  • A fal account and API key if you want generated sprites, 3D models, or audio.
  • Blender if you need to render 3D models into game-ready sprites.

Steps: how to install Universal Modder in Codex

  1. Check environment prerequisites

    What to do

    Open a terminal in your mod working folder. Check that Python, uv, and ffmpeg are installed and accessible on your PATH.

    Command

    Command
    python --version
    uv --version
    ffmpeg -version

    What you should see

    Each command outputs its installed version number.

    If something goes wrong

    If tools are missing on Windows, install them using winget and open a new terminal:

    Command
    winget install Python.Python.3.12
    winget install astral-sh.uv
    winget install Gyan.FFmpeg
  2. Add the marketplace in Codex

    What to do

    Run the marketplace addition command to register the universal-modder repository with Codex’s plugin registry.

    Command

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

    What you should see

    Codex registers the marketplace source rehan-remade/universal-modder.

    If something goes wrong

    If Codex reports an error resolving the repository, check your internet connection and verify Git is available on your PATH.

  3. Install the plugin

    What to do

    Install the plugin from the registered marketplace using the documented plugin command.

    Command

    Command
    codex plugin add universal-modder@universal-modder

    What you should see

    Codex installs the universal-modder plugin and registers its skills and MCP configuration.

    If something goes wrong

    If Codex cannot find universal-modder@universal-modder, ensure the marketplace addition command succeeded before retrying.

  4. Set the fal API key for generated assets

    What to do

    If you want the agent to generate sprites, textures, 3D models, or audio, set your fal API key in the environment. Codex configures the fal MCP server in .codex/config.toml with bearer_token_env_var = "FAL_KEY".

    Command

    Windows terminal:

    Command
    setx FAL_KEY your_key

    macOS or Linux terminal:

    Command
    export FAL_KEY=...

    What you should see

    fal displays your new key once when generated, so store it securely.

    If something goes wrong

    On Windows, open a new terminal after running setx so processes pick up the new variable. You can use the plugin without a fal key; asset generation will be skipped.

  5. Describe your mod in natural language

    What to do

    Start Codex in your mod folder. The plugin links skills via .agents/skills and provides default prompts. Describe the change you want in natural language, or use a documented default prompt from the plugin manifest:

    Command

    Command
    Mod this game: add a new weapon with fal-generated sprites

    What you should see

    The agent starts with the mod-any-game skill, searches the knowledge base, runs recon to pick a route, backs up saves, and creates MODLOG.md in your mod folder.

    If something goes wrong

    The agent asks before driving mouse and keyboard input, installing loaders into game folders, changing the registry, or publishing. It explicitly refuses to bypass anti-cheat, DRM, or game ownership checks.

Verify it worked

  • Confirm that python --version, uv --version, and ffmpeg -version report installed tool versions.
  • Confirm that Codex registers the universal-modder plugin in your environment.
  • Check that .codex/config.toml connects to https://mcp.fal.ai/mcp when FAL_KEY is present.
  • Prompt Codex in natural language to inspect your game and verify that MODLOG.md is created in your working folder.
  • Test any created mod directly inside the real game client yourself.

FAQ

How do I install the Universal Modder Codex plugin?

Add the marketplace with codex plugin marketplace add rehan-remade/universal-modder, then install the plugin with codex plugin add universal-modder@universal-modder, and launch the skill.

Can I use the plugin without a fal API key?

Yes. The plugin can still be used for engine reconnaissance, reverse engineering, save backups, and code editing. An API key is only needed if you want fal to generate 2D sprites, 3D meshes, or audio.

Do I need a paid subscription to use Codex with Universal Modder?

The universal-modder plugin is free and open source under MIT. Using Codex depends on your AI model access or subscription plan, while fal asset generation is a separate paid service.

What should I do if Codex fails to locate the universal-modder plugin?

Verify that your Codex environment has successfully registered the marketplace repository. You can re-run codex plugin marketplace add rehan-remade/universal-modder and check that your local .codex/config.toml includes the proper plugin entries.

How do I resolve path issues when running Codex on Windows?

Ensure Python and uv are registered in your Windows system PATH environment variable. Running terminal prompts in PowerShell or Command Prompt with administrator privileges is generally unnecessary; a standard terminal in your target mod workspace is recommended.