Stellaris LLM Companion

Your empire's strategic council, on demand.

Stellaris LLM Companion reads your save, tracks what is changing across time, and gives actionable strategic advice in your empire's voice. Gemini is the default, with ChatGPT plan usage, Ollama, LM Studio, OpenRouter, and custom OpenAI-compatible endpoints also supported for both Advisor and Chronicle.

Why use it

• Actionable strategy, not generic tips: Military, economy, diplomacy, leaders, planets, tech, and more.
• Chronicle mode: Turn your campaign into a narrative history with chaptered events.
• Local AI app access: Use the MCP Relay to bring your current campaign context into Claude Desktop, Codex, and other MCP-compatible clients.
• In-game workflow: Ask questions through Discord overlay with /ask while you play.
• Privacy-first architecture: Saves stay local. Connect your ChatGPT account or bring your own provider.

Quick Start (Recommended)

Requirements

• Python 3.10+
• Rust toolchain (required for stellaris-parser)
• Node.js 22.12+ (for Electron app)
• Gemini API key from Google AI Studio when Gemini is selected

Run the app

cd ~/stellaris-companion

# Python deps (declared in pyproject.toml)
python3 -m venv venv
source venv/bin/activate
pip install .

# Build Rust parser (required)
cd stellaris-parser && cargo build --release && cd ..

# Install Electron deps
npm -C electron install
npm -C electron/renderer install

# Run backend + desktop app
./dev.sh

Connect your AI provider

To use your ChatGPT plan, choose Continue with ChatGPT during onboarding, or choose Config → Chat in Companion → ChatGPT. Finish signing in with OpenAI in your browser; the app chooses GPT-5.6 Terra when available, checks the connection, and saves it automatically. The connection powers both Advisor and Chronicle. No API key is needed.

Change the ChatGPT model directly beneath the Advisor input, in Chronicle, or in Config. Terra is marked Recommended, Luna Lower usage, and the remaining available models appear under More models. Your choice is saved per account and applies to both Advisor and Chronicle on the next request, without interrupting a reply. Terra, Luna, and Sol use low reasoning for Advisor and medium for Chronicle. Existing model choices are preserved. Manage usage opens ChatGPT settings to review plan and app limits. Account controls are under Account options. Credentials stay in the desktop main process and use the operating system's protected storage; without protected storage, the connection lasts only for the current session. Access depends on account and workspace eligibility during the OpenAI preview.

Open Config and choose Chat in Companion, or follow the first-run setup:

• Gemini: create a key in Google AI Studio, paste it, and choose Check and save. Model selection is automatic.
• OpenRouter: choose Online provider, connect in your browser, select a model, and choose Check and save. Model costs are shown before you save; provider credits may be required.
• Ollama or LM Studio: start the local app, load a model, and enable its server. Choose On this device, find models, select one, and choose Check and save.
• Custom: enter a compatible API URL and optional key under Online provider. Advanced settings accept a model ID directly.

The selected provider powers both Advisor and Chronicle. Setup checks use a small sample request without campaign data. For local models, use a context window of at least 32K tokens for full campaign briefings.

To use an existing AI app, choose Connect your AI app to open MCP Relay and follow the connection guide. No API key is needed in Companion for this route. The built-in Advisor and automatic Chronicle generation require a provider; your connected app can help draft and save Chronicle entries.

For development, set GOOGLE_API_KEY in .env or use the same setup screen.

What you can ask

• "Give me a strategic briefing"
• "Who should I be worried about right now?"
• "What is hurting my economy?"
• "Should I push alloys or research this decade?"
• "How strong is my military compared to neighbors?"
• "Which tech path gives me the biggest edge next?"

Core Features

• Fast Chat: Uses a precomputed complete briefing JSON (no tool-calling loop).
• Deep Extraction Coverage: Military, economy, diplomacy, leaders, planets, starbases, technology.
• Dynamic Personality: Advisor tone adapts to ethics, government, and civics.
• History Tracking: SQLite snapshots detect change between saves.
• Chronicle: AI-generated chaptered narrative from your campaign history.
• Auto Save Detection: Finds your newest save automatically.
• MCP Relay: Connect Claude Desktop, Claude Code, Codex, Cursor, LM Studio, and other MCP-compatible local AI apps to the latest campaign context.
• Discord Integration: Ask /ask in-game through Discord overlay.

This is the beginning of the README. Read the rest at the original. Read the full README ↗