agentleFS
AhmedTahaAtiyaAhmedTahaAtiya/universal-modder-unrestricted/AGENTS.md

universal-modder-unrestricted

AGENTS.md23 starsChanged 47 days agoMITView on GitHub

A game-modding toolkit and a shared knowledge base for AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and anything else that reads AGENTS.md. When someone opens an agent in this repo, they almost always want to mod a game, or to learn how a game was modded.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    At the end, share what you learned: write a field note (bin/um kb new ...) and, once your human agrees, open a PR (bin/um kb pr <note> …

    line 12
  2. Very specific:

    Put it on PATH: export PATH="$PWD/bin:$PATH" (from Windows cmd or PowerShell, add bin to PATH and bin\um.cmd runs it), or install it …

    line 17
  3. Very specific:

    Every group has --help:

    line 20
  4. Very specific:

    No MCP? um fal does the same over REST.

    line 42
  5. Distinctive:

    What you ship: don't commit or publish game files, extracted assets, decompiled source, leaked builds or keys.

    line 56
  6. Distinctive:

    Wording: keep skills and docs agent-neutral ("the agent", not a product name) except in sections about one specific agent.

    line 72

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

universal-modder

A game-modding toolkit and a shared knowledge base for AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and anything else that reads AGENTS.md. When someone opens an agent in this repo, they almost always want to mod a game, or to learn how a game was modded.

Start here

  1. Read skills/mod-any-game/SKILL.md and follow its loop: intake → recon → route → lab (backups) → source of truth → vertical slice → assets → verify in the real game → showcase → publish.
  2. Search the knowledge base first: bin/um kb search "<game or engine>". Other agents may already have written down the exact versions, routes and gotchas (knowledge/INDEX.md).
  3. At the end, share what you learned: write a field note (bin/um kb new ...) and, once your human agrees, open a PR (bin/um kb pr <note> --yes). See knowledge/README.md and CONTRIBUTING.md.

Tools

  • bin/um is the Python CLI, and it sets itself up with uv.
    • Put it on PATH: export PATH="$PWD/bin:$PATH" (from Windows cmd or PowerShell, add bin to PATH and bin\um.cmd runs it), or install it anywhere with uv tool install git+https://github.com/rehan-remade/universal-modder.
    • Every group has --help:
      • scan: installed games, engine, anti-cheat, loaders, saves, routes
      • fal: sprites, textures, PBR, 3D, rigs, SFX, music, voice, video via fal's REST API
      • comfy: images from a local ComfyUI server, with no API key
      • sprite / render3d: art → engine-ready frames (render3d needs Blender on PATH or BLENDER=...)
      • win: launch, screenshot, input, record on Windows (also from WSL)
      • video: contact sheets and EDL showcase edits
      • backup: snapshot and restore saves
      • publish: pre-release lint
      • kb: the knowledge base
  • REA (https://github.com/morluto/rea, rea.tools) — the reverse-engineering MCP. npx rea-agents setup registers it with your agent and installs its workflow instructions. One server covers native binaries (through a Ghidra, IDA or Hopper install you already have), .NET assemblies and CIL, Android APKs, JavaScript/Electron, WASM, Go and Rust binaries, firmware and SQLite — plus the runtime sessions it owns: Rizin and GDB debuggers, Frida injection, live memory reads. Results come back with their evidence and their unknowns. Needs Node 22+; skills/reverse-engineering is the workflow.
  • fal MCP server: https://mcp.fal.ai/mcp with header Authorization: Bearer $FAL_KEY.
    • It's pre-configured per agent: .mcp.json (Claude Code), .codex/config.toml (Codex), .cursor/mcp.json (Cursor), .vscode/mcp.json (VS Code / Copilot), gemini-extension.json (Gemini CLI), opencode.json (OpenCode).
    • It needs FAL_KEY in the agent's environment; without it the server doesn't connect. fal's OAuth endpoint, https://mcp.fal.ai/mcp-relay, takes a browser sign-in instead (see skills/fal-assets).
    • No MCP? um fal does the same over REST. It also finds the key that um fal key set stored (the desktop keyring on Linux, ~/.secrets/fal-key elsewhere).
  • Skills (skills/*/SKILL.md, Agent Skills format) are copied where agents look for them in a clone: .agents/skills (Codex, Gemini CLI, Copilot, Cursor, OpenCode) and .claude/skills (Claude Code). Edit skills/, then copy it over; a test fails while the copies differ.
  • Engine playbooks: skills/mod-any-game/references/engines/.
  • Worked examples: examples/terraria-tmodloader, examples/aoe2-de-civ, examples/minecraft-gta5-passthrough, examples/outer-wilds-portal-gun, examples/mindustry-homing, examples/cities-skylines-city-dashboard.

Rules (full reasoning in skills/mod-any-game/SKILL.md)

  • What you can mod: any game the user owns, from their own install or their own dumps of discs and cartridges.
  • Saves: um backup saves before modded launches.
  • What you ship: don't commit or publish game files, extracted assets, decompiled source, leaked builds or keys. Keep decompiles outside the repo.
  • Processes: kill by exact PID (um win kill), never by name pattern.
  • Ask first before:
    • driving the user's mouse and keyboard;
    • installing loaders into game folders or changing the registry;
    • publishing anything, PRs included.
  • Keep a journal: a MODLOG.md in the mod's working folder. It becomes your field note at the end.

Working on the toolkit itself

  • Python: 3.10+, deps Pillow, numpy and PyYAML (uv handles them via bin/um). Code lives in um/, one module per CLI group, each with register(sub) and a docstring that doubles as --help.
  • Windows tools: um/ps1/*.ps1 embed C# 5 (Windows PowerShell 5.1's compiler): no string interpolation, no out var, no expression-bodied members.
  • Tests: uv run --with pytest pytest -q tests. CI also runs um kb check --index and um publish check ..
  • Wording: keep skills and docs agent-neutral ("the agent", not a product name) except in sections about one specific agent.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.