Modkeel

Compile the mods Mojang left behind

Modkeel is a CLI tool that finds, compiles, and verifies unofficial Minecraft mod forks for versions the original authors don't support. When Mojang releases a patch version (like 1.21.10), major mods skip it -- but community forks exist on GitHub as uncompiled branches. Modkeel finds them, builds them, and validates the output.

Playing the mods, not building them? The Modkeel Companion mod backs up your worlds when your mods change and fixes crashes in one click.

Quick Start

pipx install modkeel        # or: pip install modkeel
modkeel compile repos.txt -m 1.21.10 -l neoforge -lv 64 -t "$(cat github_token.txt)"

Quick Demo

Search for a mod

Compile mods from a list

Check status

GIFs generated with VHS. See demo/README.md to regenerate.

How It Works

For each repository in your list, Modkeel runs:

1. Modrinth Check -- Search for a pre-compiled JAR first (skip compilation if found)
2. Fork Discovery -- Search GitHub for compatible forks and independent ports
3. Branch Scoring -- Rank branches by version match, loader match, and freshness
4. Pre-validation -- Check gradle.properties via GitHub API before cloning
5. Cross-loader Fallback -- If no NeoForge match, try Fabric forks via Sinytra Connector
6. Compile -- Clone, run gradlew build, validate output JAR
7. Multi-pass Dependencies -- Retry failed mods with mavenLocal() after others succeed
8. Docker Testing (opt-in) -- Boot a headless MC server to verify mods load

Requirements

• Python 3.10+
• Git (in PATH)
• JDK 17 or 21 (for Gradle compilation)
• Docker (optional, for --docker-test)

python --version  # 3.10+
git --version
java -version     # 17 or 21

Installation

pipx install modkeel        # isolated install of the `modkeel` command (recommended)
pip install modkeel         # or into the current environment

From source, to work on Modkeel itself:

git clone https://github.com/Modkeel/modkeel.git
cd modkeel
pip install -e ".[dev]"

Releases and their notes: GitHub Releases.

Usage

Compile Mods

modkeel compile repos.txt \
  --mc-version 1.21.10 \
  --loader neoforge \
  --loader-version 64 \
  --github-token "$(cat github_token.txt)"

Compile and Install to Instance

modkeel compile repos.txt \
  -m 1.21.10 -l neoforge -lv 64 \
  --instance "/path/to/minecraft/instance" \
  -t "$(cat github_token.txt)"

Compile and Test in Docker

modkeel compile repos.txt \
  -m 1.21.10 -l neoforge -lv 64 \
  --docker-test \
  -t "$(cat github_token.txt)"

Search Without Compiling

modkeel search "Create" -m 1.21.10 -l neoforge -t "$(cat github_token.txt)"

Get One Mod

modkeel get "Create" -m 1.21.10 -l neoforge -lv 21.10.64

get (and search, without downloading) tries, in order, and prints what it tried:

1. The mod's official build for that Minecraft version.
2. An official build for an older version of the same line that still runs on it: its metadata must allow your version, every Minecraft class it uses must exist there, no method or field it calls may have been removed or renamed since the version it was built for, and its mixins must still find their targets (with matching parameters). A static check, so test it in game (or with --docker-test).
3. A community fork compiled for that version (needs a token and -lv).
4. Last resort: an older official build refused only by its declared Minecraft range. Modkeel adds your version to that range, but keeps the result only if its bytecode resolves and a headless server boots with it (needs Docker). The file is renamed ...+modkeel-relaxed-... and carries META-INF/modkeel-relaxed.txt.

It never downloads a different mod with a similar name: addons are listed separately.

When nothing runs on your version, Modkeel looks for the nearest Minecraft version with an official build and says so: in a terminal a 15-second countdown starts the search (Enter starts it now, n stops it); without a terminal it only prints the command to run. --fallback auto|never decides without asking. A result for another version goes to out/mc-<version>/ and is never installed into --instance. compile does the same for the whole list (never with --strict): it proposes a version where more of the mods have an official build than were built on yours. On the few versions nearest yours, a mod also counts when its older build passes the static checks there. JARs from the first run that also pass the static checks on the new version are copied instead of built again; mods with an official build there are downloaded fresh.

The last lines say what the JAR passed (Evidence: metadata ✓ · linkage ✓ · ...). With --docker-test, a headless server boots with each result before it is accepted: a JAR that crashes it (for example a mixin whose target changed) is removed and the next candidate is tried. Without Docker the JAR is kept and the output says the test did not run.

compile follows the same order for each repository, with one more step after the official build: the author's own branch for that version, prebuilt or compiled, comes before an older build. --strict never uses an older build. The report says which source each mod came from and, for failures, everything that was tried.

Check Status

modkeel status

Legacy: python mod_auto_compiler.py ... still works but is deprecated. Use modkeel compile instead.

Repository File Format

The repos.txt file contains one repository URL per line:

# Base URL -- Modkeel finds the best branch automatically
https://github.com/Creators-of-Create/Create
https://github.com/mezz/JustEnoughItems

# Specific branch
https://github.com/PepperCode1/Continuity/tree/1.21.10/dev

# Comments start with #

Command Reference

modkeel compile

modkeel search

modkeel status

No arguments. Shows version, config, cached loaders, and known NeoForge versions.

modkeel move

Moves a pack to another Minecraft version: point it at a mods folder (it is only read) and the version you want, and the whole pack lands in out/mc-<version>/.

modkeel move ~/.minecraft/mods -m 1.21.10
modkeel move "All the Mods 10" -m 1.21.10     # an instance, by name

Each JAR is identified exactly by its hash on Modrinth (no name to guess). For one Modrinth does not know, Modkeel reads what your launcher recorded when it installed the mod (Prism's mods/.index, CurseForge's minecraftinstance.json, a packwiz pack): a Modrinth project id there is exact too, and a CurseForge-only mod is reported as such. Otherwise the id and name in the JAR's metadata are looked up and marked as a guess. Then every mod goes through the same sources as get. A JAR that is on no catalog is checked as it is: if your own file passes the checks on the new version, it is reused. When some mods have no build there, Modkeel proposes the nearest version where more of the pack runs (--fallback ask|auto|never). Shared dependencies are downloaded once.

When the pack is a Prism Launcher instance, the moved pack is also added to Prism as a new instance next to it, " ()": the loader at a version for the new Minecraft, the moved mods, your settings, options.txt, config/, resource and shader packs. Your worlds are not copied (opening one on a new version upgrades it for good: copy it yourself, from a backup), and the old instance is never changed. --no-new-instance leaves only the folder. The Modrinth App and CurseForge keep their instances in their own database, so for them the pack stays in out/mc-<version>/.

modkeel instances

Lists the instances of the launchers on this machine (Prism Launcher, Modrinth App, CurseForge, and the official launcher's .minecraft/mods) with their Minecraft version, loader and number of mods, so modkeel move can take an instance's name instead of a folder. Nothing is changed; --json prints them for scripts.

$ modkeel instances
 Name              Minecraft   Loader             Mods   Launcher
 All the Mods 10   1.21.1      neoforge 21.1.77   412    Prism Launcher
 Cobblemon         1.21.1      fabric 0.16.14     88     Modrinth App

modkeel serve --stdio

Runs the engine for another program (the upcoming Modkeel app, a script, an editor plugin) over JSON lines on stdin/stdout: you send a request, Modkeel streams back its progress as events, asks the questions only you can answer (move to another Minecraft version? a GitHub token?) and ends with a result. Nothing but protocol lines is written to stdout.

$ modkeel serve --stdio
{"type":"hello","protocol":1,"modkeel":"0.1.5","methods":["get","instances","move"]}
{"type":"request","id":"1","method":"get","params":{"query":"Sodium","mc_version":"1.21.10","loader":"fabric"}}
{"type":"event","id":"1","event":{"kind":"mod_identified","query":"Sodium","title":"Sodium",...}}
...
{"type":"result","id":"1","result":{"mod":"Sodium","target":"1.21.10","delivered":{...},...}}

A question ({"type":"question","qid":"1.1",...}) waits for {"type":"answer","qid":"1.1", "value":...}; an answer of the wrong type, or closing stdin, takes the safe choice (keep the version, no token). {"type":"cancel","id":"1"} stops a request. The full message list is in modkeel/core/wire.py.

GitHub API Token

Without a token you're limited to 60 API requests/hour. With a token: 5,000/hour.

1. Go to github.com/settings/tokens
2. Generate new token > Tokens (classic)
3. Select scope: public_repo (only permission needed)
4. Save the token: echo "ghp_xxx..." > github_token.txt

Troubleshooting

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

MIT License -- see LICENSE for details.