Core Companion

Bring a companion into your Minecraft world who can talk with you, remember shared experiences, react to what happens around you, and join you on your adventures.

Core Companion combines AI conversation with a persistent character, relationship progression, an equipment inventory, expressive animations, and Baritone-powered movement. Customize their appearance and personality, explore together, hold hands, share a quiet moment, or ask for help gathering supplies.

Current release: 2.4.33 — Minecraft 26.3, Fabric.

Requirements

• Minecraft 26.3
• Fabric Loader 0.19.5 or newer
• Fabric API for Minecraft 26.3
• GeckoLib 5.5.7 or newer, compatible with Minecraft 26.3
• Java 25
• Mod Menu — optional, recommended for accessing the configuration screen
• Ollama for the default local AI setup, or a compatible configured AI endpoint

Install the main core-companion-2.4.33.jar. The companion-specific Baritone fork is already bundled inside it—do not install a separate Baritone jar for this mod.

This build is not for Minecraft 1.21.11. Back up your worlds and instance before upgrading.

Setup & First Run

Core Companion guides you through its initial setup in-game.

1. Choose your AI setup. For local AI, install Ollama and make sure it is running. Alternatively, configure a compatible OpenAI-style chat endpoint.
2. Let the local model prepare. The default setup estimates your available hardware resources, selects a model, and downloads and warms it up. Download progress appears above your hotbar.
3. Choose a character preset. Female and male starting presets are available.
4. Choose how your story begins. Start with a bonded partner, or meet unbonded village companions and build a relationship over time.

The automatic local model choices are:

• dolphin-phi — lightweight
• dolphin3 — balanced
• dolphin-mixtral — for substantially higher-memory systems

Hardware detection is an estimate, not a performance guarantee. You can change the model, provider, personality, and other settings through the in-game configuration screen.

If Ollama cannot be reached, the mod displays setup guidance. Initial local-AI setup waits for the model to become ready.

Local AI Hardware Guidance

Running Minecraft and a local AI model together uses more resources than running either alone. Shaders, high-resolution resource packs, larger AI contexts, and optional vision features can increase memory demand further.

For local AI alongside Minecraft, our recommended target is at least 12 GB of dedicated VRAM, with 16 GB or more providing additional headroom. These are guidelines—not a tested universal minimum or a guarantee of smooth performance.

• 6–8 GB VRAM: smaller models may work, but leave less room for demanding Minecraft settings.
• Larger models: require considerably more memory; 16 GB does not mean every model will fit.
• Apple Silicon: uses shared memory, which must also accommodate Minecraft and the operating system.
• CPU inference: is possible, but response speed depends heavily on the model and hardware. Ollama can also split a model between CPU and GPU memory. See Ollama’s memory guidance.

Check GPU and driver compatibility before choosing a local setup—VRAM capacity alone is not enough. See Ollama’s hardware support documentation.

Using a remote chat provider removes the need to run the chat model on your own graphics card. Minecraft and any locally enabled vision or speech-processing features still need their own resources.

A Companion With Personality

• Chat through normal Minecraft chat or /corecompanion ask.
• Customize their name, personality, appearance, and response settings.
• Build a shared history through conversations and gameplay.
• Receive reactions to exploration, building, mining, combat, weather, gifts, and social interactions.
• See expressions and animations that reflect activities and emotional state.
• Configure chat history, response length, temperature, model, endpoint, and provider settings.

Ollama is the default local backend. Compatible OpenAI-style endpoints can also be configured, including supported local servers and cloud services. Compatibility and available features depend on the endpoint and model.

AI-generated replies can be inaccurate or misunderstand context. Conversation quality varies with the model you use.

Movement & Survival Help

Your companion uses a bundled, modified Baritone system to navigate the world.

• Follow you across terrain, climb steps and ladders, swim, and attempt parkour routes.
• Break or place permitted blocks to reach you when those options are enabled.
• Bridge gaps and build upward using suitable materials.
• Use a carried water bucket for supported planned falls and emergency clutches.
• Recognize safe slime-block landings without unnecessarily covering them in water.
• Travel to saved locations and use building/template tools.
• Equip armor and weapons, eat available food, use healing items, and respond to threats.

Navigation depends on terrain, available materials, permissions, and the companion’s current state. Not every route is possible, and Elytra navigation is not currently supported.

Simple Task Offers

Companions can volunteer two kinds of gathering jobs:

• Gather logs
• Hunt pigs, cows, chickens, or sheep for food

They ask first and wait for your answer. Automatic task offers do not include crafting, farming, fishing, smelting, ore mining, or complicated multi-step plans.

Resource mining starts through the companion inventory’s Gather interface. It is not a general chat-triggered or volunteered mining job.

Farming shortcuts, torch-path jobs, and the Farmer, Miner, and Hauler roles are unavailable in this release.

Death-Drop Recovery

A sufficiently close companion can attempt to collect your dropped items and bring them back after you die.

Recovery currently requires the companion to be alive and in the same dimension when it starts. Items must still exist and be reachable; this is not a guarantee against despawning, destruction, or incompatibility with grave/container mods.

Inventory & Equipment

The companion inventory includes:

• Armor, main-hand, and offhand equipment slots
• Backpack storage
• A dedicated diary slot
• A rotatable 3D companion preview
• Health, food, and oxygen information
• Build and Gather controls
• Search, amount selection, and scrolling controls

You can transfer equipment and supplies, choose gathering targets, and control which materials may be used for navigation. Protected or valuable items are not intended to become disposable bridge filler.

Relationships & Interactions

Relationships develop through conversation, feeding, and time spent together:

Stranger → Acquaintance → Friend → Close → Dating → Bonded

Interaction unlocks include:

Relationship	Examples
Stranger	Wave
Acquaintance	High five
Friend	Lean and access to additional companion controls
Close	Shoulder carry and requesting the diary
Dating	Handholding, hugs, and kisses
Bonded	The highest relationship tier, including occasional gifts

Relationship perks can also provide defensive help, food sharing, and an emergency golden apple at critical health, subject to their eligibility checks and cooldowns.

Stay Here makes your companion remain seated. Follow Me releases that state.

Companions can sleep in suitable nearby beds, including supported adjacent-bed and shared-bed arrangements. Handholding, kissing, and affection settings are configurable.

Some interactions require the companion’s agreement, sufficient proximity, and a compatible physical state.

Answering Requests

When your companion asks permission, use the displayed Yes / No buttons or reply naturally in chat.

Only one actionable question is pending at a time. The answer window begins when the question is displayed, and ambient commentary pauses around questions and replies so you have time to respond.

Permission to teleport once is separate from permission to teleport automatically in future.

Her Diary

Your companion can record shared experiences and turn them into first-person diary entries.

Once your relationship is close enough, you can ask to borrow the diary. If she agrees, you receive her actual book rather than an unlimited duplicate.

The normal loan lasts approximately 2½ minutes of active server time. Return waits for appropriate conditions, including the same living companion being nearby and the registered book being available in the borrower’s inventory. Offline time and paused single-player reading do not consume the loan timer.

Village Companions

Choose the village start mode to meet companions before recruiting them.

New village residents receive varied starter equipment drawn from leather, gold, copper, and iron armor, alongside basic weapons or tools and an optional shield.

They stay around a village home area, wander, rest, and defend against nearby threats. Generated equipment is saved rather than rerolled every time the world loads, and recruited companions keep their existing gear.

Companion Modes & Controls

The companion’s game mode is configured separately from the player’s:

• Survival: ordinary material use and configured world-interaction permissions.
• Adventure: disables block breaking, block placement, and attacks while retaining supported travel, social, and inventory interactions.
• Creative: provides unlimited construction materials for supported building and navigation operations. It does not turn the entire inventory into unlimited items.

Additional controls include:

• Roles: Idle or Guard
• Care modes: Passive, Balanced, Guard, Retreat, or Full
• Combat policy: Passive, Defend, or Assist
• Navigation permissions: separate block-breaking and block-placement settings

Mood-driven automatic guarding respects passive combat and stands down after danger clears. An explicitly selected Guard role or guard care mode remains a deliberate instruction.

Voice, Vision & Interface

Optional features include:

• Push-to-talk voice input: hold the configured key to record, then release to send it for transcription.
• Local speech-to-text through a configured whisper.cpp setup.
• Text-to-speech through configured OpenAI or ElevenLabs services.
• Optional game-view image analysis through a configured Ollama vision model.
• On-demand vision capture and configurable automatic capture.
• A companion status HUD and optional navigation/debug overlays.
• In-game settings for character, AI providers, voice, vision, movement, and interactions.

Voice and vision require their own configuration and may add processing load or provider costs.

Privacy & External Services

Your privacy depends on which services you configure.

• Chat: messages and supplied game context go to the selected chat endpoint.
• Text-to-speech: spoken text goes to the selected voice provider.
• Vision: captured game images go to the configured vision endpoint; generated descriptions may then become part of chat context.
• Local models: run on your machine when configured locally, but initial model downloads require internet access.

Configure each feature separately. Local chat does not automatically mean that every optional feature is local.

Useful Commands

/corecompanion help
/corecompanion ask <message>
/corecompanion spawn
/corecompanion recall
/corecompanion where
/corecompanion carry
/corecompanion dismount
/corecompanion action follow
/corecompanion action stay
/corecompanion action stop
/corecompanion reload

Additional setup, interaction, and developer commands are available where enabled.

Development Status & Installation Help

Core Companion is actively developed. Some systems remain experimental, and behavior can vary between models, modpacks, and worlds. Keep backups before updating.

If you struggle with installation, an AI assistant such as ChatGPT, Claude, or Gemini may help explain error messages. Provide your Minecraft version, Fabric Loader version, mod list, graphics card, operating system, and the relevant section of latest.log.

Remove API keys, access tokens, passwords, and private information before sharing logs or configuration. AI-generated troubleshooting advice can be wrong, so back up your instance before following instructions that change or delete files.