Askcraft
- By
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. The AI navigates your `mods/`, `datapacks/` and `config/` folders with local read-only tools
# 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.
The Askcraft Team
