# AskCraft

**Ask a question in chat. An AI answers it by reading the mods you actually have installed.**

AskCraft is a **client-side** Fabric mod that adds the `/ask` command. Instead of guessing from

training data, the AI navigates your `mods/`, `datapacks/` and `config/` folders with local,

read-only tools.

That means it knows **your** pack: the datapack that overrode a spawn table, the config value the

pack author tuned, the item a mod added last week.

---

## Why it's different from a wiki or a plain chatbot

| | Wiki / chatbot | AskCraft |

|---|---|---|

| Knows your mod list | No | Yes — indexes installed mods |

| Knows your datapacks | No | Yes, **including overrides** |

| Knows your pack's config tweaks | No | Yes — reads `config/` |

| Up to date with mod versions | Often stale | Reads the jars you have |

AskCraft also respects **load precedence**: when a datapack overrides a mod's file, it answers from

the file the game actually uses, and can tell you the pack customized it.

---

## Requirements

| | |

|---|---|

| Minecraft | 1.21.1 |

| Mod loader | Fabric Loader 0.16+ |

| **Fabric API** | required |

| **Cloth Config** | required (v15+) |

| Mod Menu | optional (opens the settings screen) |

| Java | 21 |

| Side | **Client only** — no server install needed, works on any server |

| AI provider | An API key (free tier is enough — see below) |

---

## Setup

### 1. Install

Drop `askcraft-x.y.z.jar` into your `mods/` folder, along with **Fabric API** and **Cloth Config**.

### 2. Get a free API key

AskCraft needs an AI provider. The default is **Google Gemini**, which has a free tier:

1. Go to **https://aistudio.google.com/app/apikey**

2. Sign in and click **Create API key**

3. Copy it

> Other providers work too — see [Providers](#providers).

### 3. Paste the key

**With Mod Menu:** Mods → AskCraft → Settings → **AI** tab → paste into **API Key** → Save.

**Without Mod Menu:** launch the game once, then edit `config/askcraft.json`:

```json

{

"provider": "GEMINI",

"apiKey": "PASTE_YOUR_KEY_HERE",

"model": "gemini-flash-lite-latest",

"language": "EN_US"

}

```

Set `"language": "EN_US"` to get answers in English (the default is Brazilian Portuguese). This

setting only affects the AI's answers — the mod's menus are English either way.

### 4. Check it works

In game:

```

/ask test → pings the AI provider and reports back

/ask status → shows the index (mods, documents, categories) and provider

```

On first launch AskCraft builds a local index of your pack. On a ~300-mod pack this takes about

**2 seconds** and is cached in `config/askcraft/index.json`; it only rebuilds when your mods,

datapacks or configs change.

### 5. Ask

```

/ask <your question>

```

Each tool call the AI makes is echoed in chat so you can see it working. A typical question

resolves in **2 rounds, about a second**.

---

## Commands

| Command | What it does |

|---|---|

| `/ask <question>` | Ask the AI |

| `/ask status` | Index stats, provider, model, agent stats |

| `/ask config` | Show the current settings |

| `/ask test` | Ping the provider — use this to verify your key |

| `/ask reindex` | Rebuild the index by hand |

---

## Settings

Opened via Mod Menu, or edited in `config/askcraft.json`.

**AI**

- **Provider** — `GEMINI` (default), `GROQ`, `OPENROUTER`, `CUSTOM`

- **API Key** — stored locally, never leaves your machine except to your chosen provider

- **Model** — change this whenever you change provider

- **Endpoint (Custom)** — OpenAI-format URL ending in `/chat/completions`

- **Answer language** — `PT_BR` or `EN_US`

**Advanced**

- **Token budget** (default 8000) — max context sent to the AI

- **Max agent rounds** (default 8) — how many tool calls the AI gets per question

**Data sources**

- **Index lang files** — item/block/entity names and descriptions

- **Index datapacks** — your pack's customizations

---

## Providers

| Provider | Suggested model | Notes |

|---|---|---|

| **Gemini** (default) | `gemini-flash-lite-latest` | Free tier: **15 requests/minute**. Each agent round costs 1 request, so a couple of back-to-back questions can hit the limit — AskCraft waits and retries automatically. |

| **Groq** | `llama-3.3-70b-versatile` | OpenAI-compatible format |

| **OpenRouter** | `meta-llama/llama-3.3-70b-instruct` | Models ending in `:free` cost nothing |

| **Custom** | — | Any OpenAI-compatible endpoint |

Models that support **tool calling** work best. If a model doesn't support tools, AskCraft falls

back to a simpler retrieval mode.

---

## Privacy and safety

- Your API key is stored **locally** in `config/askcraft.json` and is sent only to the provider you

picked.

- `config/askcraft.json` is **excluded from the index by design** — the AI cannot read it, so your

key can never end up in an answer or in a prompt.

- All file tools are **read-only** and sandboxed to `mods/`, `datapacks/` and `config/`. AskCraft

never writes to your pack.

- Your question, plus excerpts of the game files needed to answer it, are sent to your AI provider.

If that's not acceptable to you, don't install this.

---

## Known limitations

This is an early release, here's the honest list:

- **Accuracy is ~75%** on a 20-question benchmark against a large pack. It's a research assistant,

not an oracle; it can miss or hedge.

- Behaviour defined in **code** (Java) is invisible to it. It reads data files, not bytecode, so a

drop added by a mod's code may be reported as "not found in the loot tables".

- Enumeration questions ("list every X") are weaker than lookup questions.

- **World datapacks** (`saves/<world>/datapacks/`) are not indexed yet.

- The mod's own interface is English only — there is no translation file yet. The **Answer

language** setting changes what the AI writes back, not the menus.

- Groq / OpenRouter / Custom support is implemented but **not yet tested against a live key** —

reports welcome.

---

## FAQ

**Does it work on multiplayer servers?**

Yes. It's fully client-side and reads your own files. The server doesn't need the mod.

**Is it free?**

The mod is. The AI provider is up to you; Gemini's free tier covers normal use.

**Does it work with any modpack?**

Yes — that's the point. It indexes whatever you have installed. No pack-specific code.

**Does it slow the game down?**

The index builds off the main thread (~2s on a 300-mod pack) and is cached. Answering makes a

network call, so expect a second or two per question.

**Forge / NeoForge / other Minecraft versions?**

Not currently. Fabric 1.21.1 only.

Askcraft