Install Universal Modder in OpenCode

Quick install

With OpenCode already installed, run these commands in a folder where you keep development projects:

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

OpenCode works from a repository clone. The clone's opencode.json supplies the skill path and fal MCP configuration. Launch from the clone so those files belong to the active project.

Before you start

Install OpenCode using its official setup guide, and configure the model provider you intend to use. OpenCode's /connect flow handles provider connection. Your provider credentials and the optional fal asset key are separate.

Have Git and Python 3.10 or later ready. Check the shared installation requirements for uv, ffmpeg and Blender, depending on the work you want to do. Game access also depends on the game, operating system and loader; the FAQ explains how to read the project's coverage.

Record your OpenCode version in your project notes.

Step-by-step install

Step 1: Check the terminal and clone

In the terminal you will use for modding, check:

git --version
opencode --version

Then run the clone commands above. Git creates a new universal-modder directory; choose another parent folder if that destination already contains work you need. Keep a clear distinction between this toolkit checkout, your mod source, and the installed game's directory.

After cloning, inspect the files at the repository root before starting an agent session. For future updates, preserve your local changes and record which revision supplied the instructions for the mod you built.

Step 2: Inspect the project configuration

The repository's opencode.json contains:

{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": ["skills"]
  },
  "mcp": {
    "fal": {
      "type": "remote",
      "url": "https://mcp.fal.ai/mcp",
      "headers": {
        "Authorization": "Bearer {env:FAL_KEY}"
      },
      "oauth": false
    }
  }
}

OpenCode reads project configuration from the working directory and its enclosing Git project. It also merges other configuration sources; inspect your user settings if the result differs from this file. Check precedence rules in OpenCode's configuration guide.

The repository's AGENTS.md starts the modding workflow, skills/ holds its original skill definitions, and .agents/skills contains discovery copies. Keep these paths together when using the clone route.

Step 3: Make an explicit asset-service choice

If you want fal-generated assets, provide FAL_KEY in the environment that starts OpenCode. The supplied configuration uses bearer authentication and sets oauth to false; a model-provider login does not supply that key.

If you are beginning with placeholder art, add this property inside the existing mcp.fal object:

"enabled": false

Preserve the other fields and valid JSON syntax. Set it back to true when you are ready to use the configured service. OpenCode's MCP server guide covers this switch and the API-key pattern.

Keep your real key out of the repository, prompts and screenshots. The fal key troubleshooting page explains which checks apply to CLI asset generation. um comfy is another route when you already have a local ComfyUI server configured.

Step 4: Start OpenCode and load the skill

Run opencode from the repository root. Ask it to load mod-any-game, report the skill source and explain the next investigation step. OpenCode exposes discoverable skills through its skill tool; see its skill documentation for project and user-level locations.

Use a read-only discovery prompt before requesting modifications:

Load the mod-any-game skill from this Universal Modder checkout.
Tell me which instruction file and knowledge index you will use.
Report the project directory and inspect the available um help.
Do not modify the game or generate assets during this setup check.

The checkout already includes AGENTS.md. Read that existing file before asking an initialization command to create or revise project instructions.

Step 5: Verify the command-line tools

In the same environment, run:

um --help
um --version

If um is not on PATH, the standalone installation route provides a tool-manager setup that can be used from an ordinary terminal. From a Bash or Zsh terminal at the clone root, you can also add the wrapper directory for that shell session:

export PATH="$PWD/bin:$PATH"
um --help

The wrapper uses uv to prepare its Python environment. Keep existing PATH entries and use a fresh agent session after changing the environment it inherits. See the um CLI reference for the expected command groups; a command merely named um can belong to another tool.

Check that it works

Confirm the three parts independently:

1. Skills: the agent can load the intended mod-any-game definition and identify its source.
2. CLI: um --help starts in the shell used for the project.
3. Optional fal connection: the server is deliberately disabled, or you can inspect its connection status with:

opencode mcp list

A listed server is a configuration check; perform a cost-aware asset test only when you intend to use the service. Build the first game change separately from these setup checks.

Your first prompt

Use Universal Modder to investigate my installed Terraria and tModLoader.
Search the knowledge base, identify my versions and save locations,
and plan one weapon with placeholder art. List the files to create,
the smallest game-visible test and the recovery steps before building.
Keep the plan and decisions in this project's notes.

This prompt scales the Terraria example down to one weapon. Follow the Universal Modder tutorial for the remaining stages, compare the FalArsenal source example, or choose another idea from the prompt collection.

Common errors in OpenCode

• The wrong project configuration loads: check the current directory and start from the clone root. Inspect opencode.json alongside any user or managed settings. opencode debug config can show the resolved configuration; inspect it locally because expanded headers may contain credentials.
• The skill is missing: confirm the skill files exist, check their source and review skill permissions. OpenCode can hide a skill when access is denied. Continue with agent discovery checks.
• fal authentication fails: check the process environment and the supplied bearer-header configuration. This integration disables OAuth; attempting an unrelated browser login will not replace FAL_KEY.
• The CLI does not start: use um command not found and confirm the same shell can locate uv and Python.
• Cloning fails: preserve the actual Git error. If it says spawn git ENOENT, use Git and directory diagnosis.

Uninstall

For this clone-based setup, close the project in OpenCode and preserve any mod source, notes and backups before removing the toolkit clone. If you copied its settings elsewhere, remove only its skill path and fal entry from that configuration, keeping unrelated providers and tools.

OpenCode itself can remain installed for other projects. A separately installed um also remains until you follow its CLI uninstall instructions. Start OpenCode in a different project and check which skills still come from your user-level configuration.

Other agents

Use the same toolkit in Claude Code, Codex, Cursor, Gemini CLI or VS Code / Copilot. Compare their quick setup routes in the installation overview.