FAQ and troubleshooting
Questions
Does she change my world?
Only when you ask, and only within the power and style you chose. The mod adds no blocks, items or mobs and saves nothing in your world, so you can add or remove it any time. What she does (a torch, chopping, building) is done the way a player or a command would.
Does it cost anything?
The mod and her brain are free software. The AI is the one you choose: Gemini has a free tier, Ollama runs free on your own computer, and paid providers bill you directly with your own key or subscription. The dashboard shows each AI call with an estimated cost.
What leaves my computer?
By default everything runs on your computer except the AI you choose. When you talk to her, your words, a short
text description of your game and the few memories that matter go to that AI provider. With Ollama nothing leaves
your machine. Your voice stays on your computer with local Whisper, and her memories in
~/.kindred-spirit/memory/. The game and her brain talk over 127.0.0.1 only, with a token.
The project itself receives nothing from the mod.
Can she be wrong?
Yes. What she says is generated by an AI and can be wrong. She's built not to invent facts: she answers from the game, her tools, her memory and the local knowledge base, and says so when she doesn't know.
Which Minecraft versions?
Minecraft Java Edition 1.21.1 with the Fabric loader. Porting to the current release is on the roadmap. Bedrock Edition isn't supported.
Can I use her on a server?
On a LAN world with friends, yes: see Friends on LAN. On a public server she can talk, find and lead (start your messages with her name), but she can't change the server's world. Proper online servers come later.
Can I host Pip on Windows?
Not yet: her brain's scripts are written for macOS (Linux should work but is untested). Friends on Windows can join a Mac host with just the mod. Windows and Linux hosts are on the roadmap.
Can I rename her?
Yes: her name is a setting in brain.toml, and on the dashboard. Pip is ours; yours can be anyone.
When something's wrong
| Symptom | What to do |
|---|---|
| She doesn't answer at all | /kindred status shows whether her brain is connected. Start it with scripts/start.sh, then /kindred reconnect. |
| She can't hear you (on a Mac) | Start the game with scripts/play-mac.command: the launcher opened from the Dock has no microphone permission and records silence. |
| The AI check fails with 401 or 403 | The key is missing or wrong in ~/.kindred-spirit/secrets.env. Run the gateway's check to test every part. |
| No voice, or no speech-to-text | Is the local tool running? scripts/start.sh says; logs are in ~/.kindred-spirit/logs/. |
| She's slow to answer | The gateway's log shows how long each AI reply took. A faster model, or Gemini Flash-Lite, helps. |
| The game feels slower | Leave quality on auto, or set low. Turn down her liveliness switches. |
| A friend sees a blue Allay instead of her | Their game doesn't have the mod, or not the same version as yours: Update Pip. |
| A friend gets "Incompatible" or crashes | They must start the fabric-loader-1.21.1 installation, with Fabric API for 1.21.1. |
Still stuck?
Look through the open issues, or open a new one. Include your OS, Minecraft and Fabric
versions, and the logs (minecraft-kindred/logs/latest.log and
~/.kindred-spirit/logs/brain.log). Remove any API keys before you paste.