Minecraft Mod Template

Create your own Minecraft mods with the help of Claude Code! Just describe what you want your mod to do, and Claude will build it for you.

What You Need

Before you start, make sure you have:

1. Java 21 — The programming language Minecraft mods use

   • Mac: Open Terminal and run: brew install openjdk@21
   • Windows: Download from Adoptium (pick "Temurin 21")
   • Linux: Run: sudo apt install openjdk-21-jdk

2. Minecraft with Fabric Loader — So you can test your mod

   • Install the Fabric Loader for Minecraft 1.21.1
   • Also install the Fabric API mod (put the JAR in your mods folder)

3. Claude Code — The AI assistant that will build your mod

   • Follow the setup instructions at claude.com/claude-code

Getting Started

Step 1: Create Your Repo

Click the green "Use this template" button at the top of this page to create your own copy.

Step 2: Clone It

git clone https://github.com/YOUR-USERNAME/YOUR-MOD-NAME.git
cd YOUR-MOD-NAME

Step 3: Set Up Java (Mac Only)

If you installed Java with Homebrew on Mac, run this first:

export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home

Step 4: Make Sure It Builds

Before adding anything, check that the template compiles:

./gradlew build

You should see BUILD SUCCESSFUL. If not, check the troubleshooting section below.

Step 5: Design Your Mod!

Open Claude Code in your project folder:

claude

Then type your mod idea using the /design-mod command:

/design-mod A friendly dragon that follows you around and breathes fire at enemies

Claude will:

1. Ask you some fun questions about your mod idea
2. Help you pick a cool name for it
3. Write up a plan and show it to you
4. Build the whole mod once you approve the plan
5. Tell you how to test it in Minecraft

Step 6: Test Your Mod

After Claude builds your mod, run:

./gradlew runClient

This opens Minecraft with your mod loaded! Follow the testing instructions Claude gives you.

Troubleshooting

"JAVA_HOME is not set"

Run this command before building:

# Mac (Homebrew)
export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home

# Linux
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# Windows (PowerShell)
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21"

"Could not resolve dependencies" or Gradle is downloading forever

This happens the first time you build — Gradle needs to download Minecraft and the modding tools. It can take a few minutes on a slow connection. Just let it run!

"BUILD FAILED" with Java errors

Make sure you have Java 21 (not an older version):

java -version

It should say something like openjdk version "21.x.x".

Minecraft crashes when loading

• Make sure you have the Fabric Loader installed for version 1.21.1
• Make sure the Fabric API mod JAR is in your mods folder
• Check the logs/latest.log file for error messages

How It Works

This template is a minimal Fabric mod that compiles and runs but doesn't add anything to the game yet. When you run /design-mod, Claude:

1. Reads about what's possible in Minecraft modding
2. Helps you design your mod through a conversation
3. Creates all the Java code, textures, sounds, and config files
4. Makes sure it compiles and gives you testing instructions

The mod uses Fabric (a Minecraft modding framework) for Minecraft version 1.21.1.

Project Structure

your-mod/
├── src/main/          # Server & shared code + all resources
│   ├── java/          #   Java source files
│   └── resources/     #   Textures, sounds, config files
├── src/client/        # Client-only code (rendering, models)
│   ├── java/          #   Client Java source files
│   └── resources/     #   Client config files
├── build.gradle       # Build configuration
├── gradle.properties  # Mod version and dependency versions
└── docs/              # Design documents and references

Want to Make Another Mod?

Just create a new repo from this template and run /design-mod again with a different idea!