# Stellaris Companion Field Manual

> Player documentation, strategy guides, and agent-readable reference for Stellaris Companion.

Index: https://galacticfilingcabinet.com/llms.txt

# Stellaris Companion Field Manual

> Understand the platform, connect your first campaign, and give AI agents reliable context about your empire.

Source: https://galacticfilingcabinet.com/docs/ · Markdown: https://galacticfilingcabinet.com/docs/index.md

Stellaris Companion turns a changing Stellaris campaign into context that humans can inspect and AI agents can reason over. This manual explains the system from the first save import to advisor briefings, Chronicle stories, and local MCP connections.

## Start in three steps

1. **[Install Stellaris Companion](/docs/start-here/install):** download the desktop app for macOS, Windows, or Linux.
2. **[Connect your first save](/docs/start-here/connect-your-first-save):** let the Companion discover a campaign or import a `.sav` file.
3. **[Ask your first question](/docs/start-here/ask-your-first-question):** use the Advisor or connect an AI app once your campaign is ready.

Completing those three steps is enough to get a campaign-grounded answer. Everything else in the manual is optional depth.

## Other routes

- **Connecting an AI app?** See the [AI app connection guide](/docs/ai-app-connections).
- **Trying to understand the architecture?** Read [how Stellaris Companion works](/docs/how-it-works).
- **Solving an in-game problem?** Browse the [strategy guides](/guides).

## One platform, two reading modes

Every manual page has an HTML version for people and a clean Markdown twin for agents. Agents can discover the complete corpus through [`/llms.txt`](https://galacticfilingcabinet.com/llms.txt) or fetch a single page through its **Read as Markdown** link.

## What the Companion does

1. Watches or imports local Stellaris saves.
2. Parses campaign state into a local historical archive.
3. Produces focused, perspective-aware briefings.
4. Lets supported AI clients request those briefings through a local MCP bridge.
5. Helps you turn campaign events into a readable Chronicle.

Raw save files remain on your computer. See [privacy and data flow](/docs/how-it-works/privacy-and-data-flow) for the exact boundary.

# Connect an AI app

> Give a supported local AI client structured access to your Stellaris Companion archive through MCP.

Source: https://galacticfilingcabinet.com/docs/ai-app-connections/ · Markdown: https://galacticfilingcabinet.com/docs/ai-app-connections/index.md

Stellaris Companion includes a local MCP bridge. MCP-capable desktop clients can use it to request campaign briefings and structured context while the Companion remains the source of truth.

## Connection model

The AI client starts or connects to a local server configured by Stellaris Companion. When you ask a campaign question, the client calls an appropriate read-only tool, receives a focused briefing, and answers in its own conversation.

This is not a public web endpoint. Your campaign archive is not published to this website.

## Client guides

- [Codex](/docs/ai-app-connections/codex)
- [Claude Desktop](/docs/ai-app-connections/claude-desktop)
- [Other MCP clients](/docs/ai-app-connections/other-clients)

# Connect Claude Desktop

> Install the packaged desktop extension and verify local campaign access.

Source: https://galacticfilingcabinet.com/docs/ai-app-connections/claude-desktop/ · Markdown: https://galacticfilingcabinet.com/docs/ai-app-connections/claude-desktop/index.md

Stellaris Companion provides a packaged Claude Desktop connection for the simplest local setup.

## Install

1. Open Stellaris Companion and select a campaign.
2. Open **Settings**, then **MCP Relay**.
3. Choose the Claude Desktop install action.
4. Run the MCP health check.
5. Restart Claude Desktop so it discovers the extension.

In a new conversation, ask Claude to use Stellaris Companion for a campaign question. If the tool is connected but no campaign is available, return to the Companion and verify that a save has been ingested.

The extension exposes structured campaign context; it does not upload your raw save as an attachment.

# Connect Codex

> Add Stellaris Companion as a local MCP server so Codex can answer from your current campaign.

Source: https://galacticfilingcabinet.com/docs/ai-app-connections/codex/ · Markdown: https://galacticfilingcabinet.com/docs/ai-app-connections/codex/index.md

Codex can use the Companion's local MCP server when the server is present in your Codex MCP configuration.

## Configure the connection

1. Open Stellaris Companion and select a campaign.
2. Open **Settings**, then **MCP Relay**.
3. Run the health check.
4. Open **Show manual MCP setup** and copy the Codex setup command.
5. Apply it in your local Codex environment, then restart or reload Codex.

Ask Codex: “Use Stellaris Companion to assess my current campaign.” The client should select the Advisor Briefing before answering.

## Chronicle edits

Draft and revise Chronicle prose in chat first. Codex should call a save, update, create, or undo tool only after you explicitly ask it to send the text back to Stellaris Companion.

The MCP server does not edit the Stellaris save, run another model, or finalize game state.

# Connect another MCP client

> Use the generic local configuration with Claude Code, Cursor, LM Studio, or another MCP-capable app.

Source: https://galacticfilingcabinet.com/docs/ai-app-connections/other-clients/ · Markdown: https://galacticfilingcabinet.com/docs/ai-app-connections/other-clients/index.md

The MCP Relay can work with local clients that support a stdio MCP server.

## Generic setup

1. Load a campaign in Stellaris Companion.
2. Open **Settings → MCP Relay** and run the health check.
3. Open **Show manual MCP setup**.
4. Copy the Claude Code command, Codex command, or generic JSON that best matches the client.
5. Add it to the client's local MCP configuration and restart that client.

The exact configuration screen belongs to the client and may change between releases. The important contract is that it launches the Companion's local server as configured by the app.

Web-only chat products cannot normally connect directly to a private local stdio server. Use a local MCP-capable desktop or developer client.

# Chronicle

> Generate, revise, save, and optionally publish a narrative history of your Stellaris campaign.

Source: https://galacticfilingcabinet.com/docs/chronicle/ · Markdown: https://galacticfilingcabinet.com/docs/chronicle/index.md

Chronicle is the storytelling side of Stellaris Companion. It uses the same local campaign history as the Advisor, but organizes change into eras and chapters instead of recommendations.

## A safe workflow

1. Ingest enough saves for the era to have a meaningful arc.
2. Open Chronicle and generate or refresh the current era.
3. Check names, dates, outcomes, and point of view.
4. Revise in the app or a connected AI client.
5. Save approved changes to the local Chronicle cache.
6. Publish only if you want a public, shareable story page.

Read [how Chronicle generation works](/docs/how-it-works/chronicle-generation) or continue to [publish and share](/docs/chronicle/publish-and-share).

# Publish and share a Chronicle

> Create a public campaign story while keeping raw saves and the local archive private.

Source: https://galacticfilingcabinet.com/docs/chronicle/publish-and-share/ · Markdown: https://galacticfilingcabinet.com/docs/chronicle/publish-and-share/index.md

Publishing creates a public story page from the Chronicle content you choose to share. It is separate from the local campaign archive and the MCP Relay.

## Before publishing

- Review the title, summary, chapter text, and empire names.
- Remove private notes or accidental personal information.
- Confirm that the perspective and spoilers are suitable for your audience.
- Remember that a public URL can be copied beyond the people you send it to.

The published page contains narrative content and selected presentation metadata. It does not expose the raw save file or provide a public MCP connection to your local archive.

Browse examples in [Player Chronicles](https://galacticfilingcabinet.com/chronicles).

# How Stellaris Companion works

> The local pipeline from save ingestion to campaign briefings, agent tools, and player-authored stories.

Source: https://galacticfilingcabinet.com/docs/how-it-works/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/index.md

The Companion is a local-first interpretation layer between a Stellaris save and the questions a player wants to ask.

## The pipeline

```mermaid
flowchart LR
  accTitle: Stellaris Companion campaign data pipeline
  accDescr: A local Stellaris save is parsed into a campaign archive, which produces focused briefings for the Advisor and connected AI clients, plus Chronicle drafts when requested.
  Save["Local .sav file"] --> Parse["Ingest + parse"]
  Parse --> Archive["Campaign archive"]
  Archive --> Brief["Focused briefing"]
  Brief --> Advisor["In-app Advisor"]
  Brief --> MCP["Local MCP server"]
  MCP --> Client["Connected AI client"]
  Archive --> Chronicle["Chronicle draft"]
```

1. **Ingest:** discover or import a local `.sav` file.
2. **Parse:** extract structured campaign facts.
3. **Archive:** preserve snapshots so change over time is visible.
4. **Brief:** select the facts relevant to a question.
5. **Interpret:** let an advisor or connected AI app reason over that briefing.
6. **Narrate:** turn selected events into Chronicle drafts when the player asks.

Read the detailed pages on [save parsing and history](/docs/how-it-works/save-parsing-and-history), [advisor briefings](/docs/how-it-works/advisor-briefings), and [privacy and data flow](/docs/how-it-works/privacy-and-data-flow).

# Advisor briefings

> Why the Companion gives AI models a focused briefing instead of an unfiltered save dump.

Source: https://galacticfilingcabinet.com/docs/how-it-works/advisor-briefings/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/advisor-briefings/index.md

An Advisor Briefing is a purpose-built view of the current campaign. It combines the latest empire state, recent changes, selected history, known game-version mechanics, and advisor memory.

## Question-shaped context

For a strategic question, the briefing prioritizes facts that can change the recommendation. An economy question should not spend most of its context budget describing remote empires; a war-readiness question should not omit fleet composition, command limits, and replacement capacity.

The main MCP workflow follows the same rule: a connected client should request **Advisor Briefing** first and use narrower sections only for follow-up detail or a tight context budget.

## Grounding and uncertainty

A useful answer distinguishes:

- facts extracted from the campaign;
- trends inferred from multiple snapshots;
- strategic judgments made by the model;
- information hidden by the selected player perspective.

The briefing can reduce hallucination, but it cannot make a model infallible. Treat high-impact advice as a recommendation you can inspect against the visible game state.

# Chronicle generation

> How campaign events become eras, chapters, current-era prose, and editable local history.

Source: https://galacticfilingcabinet.com/docs/how-it-works/chronicle-generation/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/chronicle-generation/index.md

Chronicle turns the campaign archive into a narrative layer. It selects event clusters and state changes, then asks the configured model to produce prose in the chosen voice.

## Chapters and the current era

Finalized chapters describe completed arcs. The current era is a living section that can change as new saves arrive. Existing chapters stay readable even when the selected AI provider is offline because the generated text is cached locally.

Chronicle generation receives extracted events and bounded campaign context, not the raw `.sav` file.

## Editing from an AI client

A connected MCP client can read the cached Chronicle and request source material for a new passage. Drafting and revision should happen in chat first.

Write-back is deliberate:

- save current-era text;
- update an existing chapter;
- create a chapter;
- undo a Chronicle edit.

These actions affect the local Chronicle cache only. They do not edit game state, call the in-app provider, or declare the campaign history final.

# Player perspective and spoilers

> Keep advice grounded in what your empire could reasonably know.

Source: https://galacticfilingcabinet.com/docs/how-it-works/perspective-and-spoilers/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/perspective-and-spoilers/index.md

A save can contain information the player empire has not discovered. Useful roleplay and fair strategy advice should respect the selected perspective instead of treating hidden galaxy state as public intelligence.

## Perspective-aware answers

The Companion can frame briefings around the player empire and the knowledge relevant to it. Connected agents should avoid revealing hidden facts and should state when confidence depends on limited intelligence.

Ask:

> Answer from my empire's current perspective. Do not reveal hidden empires, crisis triggers, or undiscovered systems. Label uncertain intelligence.

## Practical limits

Perspective filtering is a product guardrail, not a proof that every possible spoiler has been removed. Save formats, mods, and new game versions can introduce fields that need new handling. If spoiler control matters to a campaign, use conservative prompts and report leaks through [feedback](https://galacticfilingcabinet.com/feedback).

# Privacy and data flow

> What stays local, what a selected AI provider receives, and what the MCP bridge exposes.

Source: https://galacticfilingcabinet.com/docs/how-it-works/privacy-and-data-flow/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/privacy-and-data-flow/index.md

Stellaris Companion is local-first, but some features can use an AI provider you select. The boundary depends on which workflow you use.

## The boundary at a glance

```mermaid
flowchart LR
  accTitle: Stellaris Companion privacy and data flow
  accDescr: Raw saves and the parsed archive remain on the player's computer. Only extracted context crosses the boundary when the player uses a selected AI provider or a connected MCP client.
  subgraph Device["Your computer"]
Save["Raw .sav file"] --> Archive["Parsed campaign archive"]
Archive --> Advisor["In-app Advisor or Chronicle"]
Archive --> MCP["Local MCP server"]
  end
  Advisor -->|"Question + extracted context"| Provider["Your selected AI provider"]
  MCP -->|"Structured briefing"| Client["Connected AI client"]
  Client -->|"Depends on client settings"| ClientModel["Client's model provider"]
```

## Always local

- Raw `.sav` files and the parsed campaign archive.
- Save discovery, extraction, history comparison, and cached Chronicle text.
- The local MCP server and its connection to a desktop AI client.
- Provider credentials, which are not included in MCP responses.

## Sent to your selected AI provider

When you use the in-app Advisor or generate Chronicle prose, the selected provider receives the question or writing instruction plus extracted campaign context. It does not need the raw save file.

Local models can keep that inference on your machine. Remote providers receive the submitted context according to their own terms and privacy policies.

## Shared with a connected MCP client

An MCP-capable app can request structured briefings, recent events, and cached Chronicle material from the local archive. The client performs the reasoning in its own process and may itself use a remote model. Review that client's privacy settings separately.

Chronicle write-back tools change only the local Chronicle cache, and agents should use them only after explicit save, apply, or send-back intent. They cannot mutate a Stellaris save.

For the public website's separate data practices, read the [website privacy notice](https://galacticfilingcabinet.com/privacy).

# Save parsing and campaign history

> How the Companion extracts structured facts and turns repeated saves into a timeline.

Source: https://galacticfilingcabinet.com/docs/how-it-works/save-parsing-and-history/ · Markdown: https://galacticfilingcabinet.com/docs/how-it-works/save-parsing-and-history/index.md

A Stellaris save is a compressed game-state document, not a ready-made story. Stellaris Companion uses a Rust parser built on Jomini to read the save and extract the domains needed by the Advisor and Chronicle.

## From file to snapshot

The extractor identifies the player empire, economy, technology, military, diplomacy, internal politics, galactic conditions, and recent event signals. The exact briefing is a bounded interpretation of those facts; it is not a copy of the entire save.

Each successful ingestion creates a timestamped snapshot in a local SQLite archive. Comparing snapshots lets the Companion identify direction:

- a deficit that is shrinking or accelerating;
- a fleet that is rebuilding after losses;
- a diplomatic relationship that changed;
- territory, population, technology, and policy changes;
- events that belong in a Chronicle chapter.

## What it does not do

The parser does not write to the `.sav` file. It does not run the game, issue console commands, or simulate an outcome. Advice is an interpretation of recorded state, not a guarantee about the next event roll.

# Reference

> Concise facts about save locations, MCP capabilities, privacy boundaries, and version scope.

Source: https://galacticfilingcabinet.com/docs/reference/ · Markdown: https://galacticfilingcabinet.com/docs/reference/index.md

- [Save locations](/docs/reference/save-locations)
- [MCP capabilities](/docs/reference/mcp-capabilities)
- [Data boundary](/docs/reference/data-boundary)

For machine-readable discovery, start at [`llms.txt`](https://galacticfilingcabinet.com/llms.txt). Every indexed page also exposes a clean `index.md` twin and its authored `index.mdx` source.

# Data boundary reference

> A compact matrix of what each Stellaris Companion surface reads, sends, and changes.

Source: https://galacticfilingcabinet.com/docs/reference/data-boundary/ · Markdown: https://galacticfilingcabinet.com/docs/reference/data-boundary/index.md

| Surface | Reads | May send | May change |
| --- | --- | --- | --- |
| Save ingestion | Local `.sav` files | Nothing by default | Local parsed archive |
| In-app Advisor | Extracted context | Prompt and context to selected provider | Advisor memory/cache |
| In-app Chronicle | Extracted events and cached prose | Prompt and context to selected provider | Local Chronicle cache |
| MCP Relay read tools | Local extracted archive | Structured context to connected local client | Nothing |
| MCP Chronicle write tools | Draft plus local Chronicle | Nothing by themselves | Local Chronicle cache after explicit intent |
| Published Chronicle | Approved story content | Public website | Public story record |

No listed surface writes to a Stellaris `.sav` file.

# MCP capability reference

> The read and write boundaries exposed to local MCP-capable AI clients.

Source: https://galacticfilingcabinet.com/docs/reference/mcp-capabilities/ · Markdown: https://galacticfilingcabinet.com/docs/reference/mcp-capabilities/index.md

## Strategic context

- **Advisor Briefing:** primary rich context for strategic questions.
- **Empire Briefing:** narrower follow-up detail when context is constrained.
- **Recent campaign context:** recent changes and events.

Use Advisor Briefing first. Do not ask the user to choose internal tools unless a capability is genuinely unavailable.

## Chronicle context

- Read the cached Chronicle archive.
- Request source material for the current era or a chapter.
- Draft and revise prose in chat.

## Chronicle write-back

Save current-era text, update a chapter, create a chapter, or undo a Chronicle edit only after explicit user intent to save, apply, create, send back, or undo.

Write-back updates the local Chronicle cache. It does not edit the Stellaris save, finalize game state, call an AI provider, or alter Advisor data.

# Save location reference

> Default Stellaris save directories by operating system.

Source: https://galacticfilingcabinet.com/docs/reference/save-locations/ · Markdown: https://galacticfilingcabinet.com/docs/reference/save-locations/index.md

| Platform | Default directory |
| --- | --- |
| macOS | `~/Documents/Paradox Interactive/Stellaris/save games/` |
| Windows | `Documents\Paradox Interactive\Stellaris\save games\` |
| Linux with Steam | `~/.local/share/Paradox Interactive/Stellaris/save games/` |
| Linux with Flatpak Steam | `~/.var/app/com.valvesoftware.Steam/.local/share/Paradox Interactive/Stellaris/save games/` |

Steam Cloud, redirected document folders, alternate launchers, and sandboxes can change these locations. See the full [save file location guide](/guides/stellaris-save-file-locations) for diagnostics.

# Ask your first question

> Use the built-in advisor or a connected AI app to get a campaign-grounded answer.

Source: https://galacticfilingcabinet.com/docs/start-here/ask-your-first-question/ · Markdown: https://galacticfilingcabinet.com/docs/start-here/ask-your-first-question/index.md

Select a campaign with at least one ingested save, open the Advisor, and ask a concrete question such as:

> What is the most urgent risk to my empire over the next ten years?

The Advisor assembles a focused campaign briefing before generating the answer. It should explain the evidence it used instead of treating the full save as an undifferentiated wall of text.

## Better first questions

- Is my economy resilient enough to expand my fleet?
- Which rival is most likely to threaten me?
- What changed since my previous save?
- What should I prepare before the endgame crisis?

For advice in Codex, Claude Desktop, or another supported client, continue to [AI app connections](/docs/ai-app-connections).

# Connect your first save

> Let the Companion find a Stellaris campaign or import a save manually.

Source: https://galacticfilingcabinet.com/docs/start-here/connect-your-first-save/ · Markdown: https://galacticfilingcabinet.com/docs/start-here/connect-your-first-save/index.md

On first launch, Stellaris Companion looks in the standard local and cloud save folders for your operating system.

## Automatic discovery

1. Start or load a campaign in Stellaris.
2. Create a fresh save.
3. Open Stellaris Companion and select the campaign when it appears.
4. Confirm that the latest in-game date and empire name look right.

If the campaign does not appear, use manual import and select a `.sav` file. The Companion reads a local copy into its archive; it does not modify the original save.

## Verify the archive

Move forward in the campaign, save again, and check that the archive gains a new snapshot. That history is what lets the Companion distinguish a current condition from a developing trend.

Next, [ask your first question](/docs/start-here/ask-your-first-question).

# Install Stellaris Companion

> Download the desktop app, pass platform security checks, and prepare it for your first campaign.

Source: https://galacticfilingcabinet.com/docs/start-here/install/ · Markdown: https://galacticfilingcabinet.com/docs/start-here/install/index.md

Stellaris Companion is an open-source desktop app for macOS, Windows, and Linux.

## Download

Use the [download section](https://galacticfilingcabinet.com/#download) for the recommended installer, or open the [latest GitHub release](https://github.com/gitmaan/stellaris-companion/releases/latest) to choose an asset directly.

## Open the app

- **macOS:** open the downloaded disk image and drag Stellaris Companion to Applications.
- **Windows:** run the installer. If SmartScreen appears, verify the publisher context and source before continuing.
- **Linux:** use the package supplied in the latest release.

The app may need permission to read the folder where Stellaris stores save games. It does not need your Paradox account password.

## Continue

Open Stellaris Companion, then [connect your first save](/docs/start-here/connect-your-first-save).

# Troubleshooting Stellaris Companion

> Resolve save discovery, platform security, provider, and MCP connection problems.

Source: https://galacticfilingcabinet.com/docs/troubleshooting/ · Markdown: https://galacticfilingcabinet.com/docs/troubleshooting/index.md

Start by identifying which boundary failed: save ingestion, the desktop UI, the selected AI provider, or the MCP client connection.

## Common paths

- [A campaign is not detected](/docs/troubleshooting/save-detection)
- [Windows SmartScreen blocks the installer](/docs/troubleshooting/windows-smartscreen)
- [An MCP client cannot connect](/docs/troubleshooting/mcp-connection)

For a bug that persists, use [Feedback](https://galacticfilingcabinet.com/feedback) and include the app version, operating system, game version, and the step that failed. Do not attach a private save unless you intend to share it with the project.

# An MCP client cannot connect

> Check the local server, client configuration, campaign state, and restart boundary.

Source: https://galacticfilingcabinet.com/docs/troubleshooting/mcp-connection/ · Markdown: https://galacticfilingcabinet.com/docs/troubleshooting/mcp-connection/index.md

## Isolate the failing side

1. Open Stellaris Companion and load a campaign.
2. Open **Settings → MCP Relay**.
3. Run the built-in health check.
4. If the check fails, resolve the Companion error before changing the client.
5. If it passes, copy a fresh client configuration and restart the client.

Many MCP clients read their server list only at startup. Reloading a chat is not always enough.

## Connected but no campaign context

Verify that the latest save finished ingestion and that the client is calling a Companion tool. Ask it explicitly to use **Advisor Briefing**.

If the client reports an unknown tool or stale schema, remove the old configuration, re-run the setup from the current Companion version, and restart again.

# A Stellaris save is not detected

> Find the actual save location, refresh ingestion, and diagnose permissions or unsupported files.

Source: https://galacticfilingcabinet.com/docs/troubleshooting/save-detection/ · Markdown: https://galacticfilingcabinet.com/docs/troubleshooting/save-detection/index.md

## Check the file first

Create a new manual save in Stellaris, then locate it using the [platform save paths](/guides/stellaris-save-file-locations). Confirm that the file has a `.sav` extension and a recent modified time.

## In the Companion

1. Refresh the campaign list.
2. Use manual import and choose the file directly.
3. Grant folder access if macOS, Windows, or a sandboxed package asks.
4. Wait for ingestion to finish before importing the same file again.

## If parsing fails

A new Stellaris patch, a total-conversion mod, a damaged save, or an unusual archive format can expose data the parser does not yet handle. Keep the original file, record the game version and mod list, and submit a [feedback report](https://galacticfilingcabinet.com/feedback).

# Windows SmartScreen blocks the installer

> Verify the download source and open an independently distributed Stellaris Companion release.

Source: https://galacticfilingcabinet.com/docs/troubleshooting/windows-smartscreen/ · Markdown: https://galacticfilingcabinet.com/docs/troubleshooting/windows-smartscreen/index.md

Windows may warn about a new or independently distributed application before it has built download reputation.

## Verify before continuing

1. Confirm that the installer came from the [official latest release](https://github.com/gitmaan/stellaris-companion/releases/latest) or this site's download button.
2. Check that the filename and version match the release notes.
3. Scan the file with your normal security tools.
4. In the SmartScreen dialog, open the additional information only after those checks.

If the file came from a mirror, unsolicited message, or unfamiliar domain, stop and download it again from the official release.

Security prompts and exact button labels can differ across Windows versions. The project should never ask you to disable antivirus protection globally.

# Stellaris strategy and storytelling guides

> Practical, campaign-aware workflows for economy, fleets, crises, roleplay, and after-action reports.

Source: https://galacticfilingcabinet.com/guides/ · Markdown: https://galacticfilingcabinet.com/guides/index.md

These guides start from a real player question and show both the in-game reasoning and the Companion workflow that can support it.

## Strategy

- [Fix a resource deficit](/guides/fix-stellaris-resource-deficit)
- [Assess fleet readiness](/guides/assess-fleet-readiness)
- [Prepare for an endgame crisis](/guides/prepare-for-endgame-crisis)

## Story and roleplay

- [Write a Stellaris after-action report](/guides/write-stellaris-aar)
- [Roleplay by ethics](/guides/stellaris-roleplay-by-ethics)

## Setup reference

- [Find Stellaris save files](/guides/stellaris-save-file-locations)
- [Use Stellaris with Claude and Codex](/guides/use-stellaris-with-claude-and-codex)

# How to assess Stellaris fleet readiness

> Evaluate combat strength, replacement capacity, positioning, and strategic objectives before declaring war.

Source: https://galacticfilingcabinet.com/guides/assess-fleet-readiness/ · Markdown: https://galacticfilingcabinet.com/guides/assess-fleet-readiness/index.md

Fleet power is a useful headline and a poor war plan. Readiness is the relationship between the forces you can commit, the forces you can replace, the route to the objective, and what must remain behind.

## Readiness checklist

- **Available force:** fleets that can reach the front, not fleets pinned by piracy, defense, or travel time.
- **Command and composition:** whether ships are grouped efficiently and suited to the expected opponent.
- **Reinforcement economy:** alloys, shipyards, naval capacity, and the time needed to replace losses.
- **Positioning:** gateways, hyperlanes, chokepoints, access agreements, and rally points.
- **Intelligence:** the confidence level behind enemy fleet and technology estimates.
- **Objective:** the systems, claims, subjects, or status change that make the risk worthwhile.

Ask the Companion:

> Am I ready for a ten-year war with my selected rival? Separate known facts from estimates and include the economic cost of replacing a quarter of my fleet.

## Define an abort condition

Decide in advance what would make you stop pushing: a second front, a depleted alloy reserve, a lost shipyard, or an enemy force above a threshold. A readiness assessment is most valuable when it changes a decision before the first battle.

# How to fix a Stellaris resource deficit

> Diagnose whether a deficit is temporary, structural, or a warning that your empire has overextended.

Source: https://galacticfilingcabinet.com/guides/fix-stellaris-resource-deficit/ · Markdown: https://galacticfilingcabinet.com/guides/fix-stellaris-resource-deficit/index.md

A red monthly number is a symptom. The useful question is whether reserves and future income can absorb it before penalties or forced cancellations compound the problem.

## Diagnose before cutting

Record four things:

1. Monthly balance.
2. Current stockpile.
3. Recent construction, fleet reinforcement, edicts, and market trades.
4. The jobs and upkeep that consume the resource.

A deficit caused by a colony ship or temporary reinforcement queue can clear itself. A growing deficit across several saves is structural.

Ask the Companion:

> Compare the last three snapshots. What is driving my energy deficit, how many months of reserves remain, and which correction has the lowest strategic cost?

## Stabilize in the right order

- Stop discretionary purchases that consume the scarce resource.
- Check whether an automated monthly market trade is masking or creating the problem.
- Reduce avoidable upkeep before dismantling productive capacity.
- Move workers and adjust planet specialization where it restores an input bottleneck.
- Use the market to bridge a short gap, not to permanently subsidize an unprofitable structure.
- Revisit fleet, starbase, and leader upkeep if you expanded faster than your economic base.

## Confirm the fix

Ingest another save after the change. A positive monthly balance is good; a trend that survives new construction and population changes is better.

# How to prepare for the Stellaris endgame crisis

> Build a campaign-specific readiness plan across economy, fleets, mobility, intelligence, and political resilience.

Source: https://galacticfilingcabinet.com/guides/prepare-for-endgame-crisis/ · Markdown: https://galacticfilingcabinet.com/guides/prepare-for-endgame-crisis/index.md

Endgame preparation is not one fleet-power target. It is the ability to absorb surprise, learn the crisis's mechanics, move force across the galaxy, and keep replacing losses.

## Five layers of preparation

1. **Economic depth:** sustained alloy output, energy for upkeep, and reserves that survive a disrupted trade network.
2. **Production:** several protected shipyards and a reinforcement route that does not depend on one chokepoint.
3. **Mobility:** gateways, relays, jump options, and forward bases that reduce response time.
4. **Adaptation:** enough research, intelligence, and redesign capacity to answer the actual crisis instead of a guessed one.
5. **Political resilience:** allies, subjects, federations, or diplomatic breathing room that prevent opportunistic conventional wars.

Ask the Companion:

> Build a crisis-readiness plan from my current empire. Rank the three weakest layers, give each a measurable target, and flag anything you cannot know from the save.

## Use checkpoints

Re-run the assessment every decade or after a major war. The history archive makes the important question visible: are you closing the readiness gap faster than the galaxy is becoming dangerous?

# Stellaris roleplay guide by ethics

> Turn empire ethics into consistent decisions, internal tensions, advisor questions, and Chronicle voice.

Source: https://galacticfilingcabinet.com/guides/stellaris-roleplay-by-ethics/ · Markdown: https://galacticfilingcabinet.com/guides/stellaris-roleplay-by-ethics/index.md

Ethics are more interesting as pressures than as commandments. Give each ethic a principle, a political constituency, and a line it fears crossing.

## Convert ethics into decisions

For every major choice, ask:

- What outcome does this ethic call legitimate?
- Which faction or institution benefits?
- What compromise would feel like betrayal?
- What event could make the empire reinterpret the ethic?

A militarist empire can seek deterrence, glory, liberation, or domination. A pacifist empire can still use coercion, proxies, fortresses, and economic power. The story lives in the chosen interpretation.

## Use the Advisor in character

Ask:

> Advise as a cautious official who shares my empire's ethics but must point out where our policy contradicts them.

Then ask for the strongest opposing view. The Companion's campaign facts keep the debate attached to actual pressures rather than generic lore.

## Let the Chronicle show change

Do not restate the ethics label in every chapter. Show it through law, diplomacy, monuments, casualties, faction conflict, and the language used to describe enemies.

For a broader starting point, see the site's [Stellaris roleplay guide](https://galacticfilingcabinet.com/stellaris-roleplay-guide).

# Where are Stellaris save files?

> Find local and cloud Stellaris saves on Windows, macOS, Linux, and Steam Flatpak.

Source: https://galacticfilingcabinet.com/guides/stellaris-save-file-locations/ · Markdown: https://galacticfilingcabinet.com/guides/stellaris-save-file-locations/index.md

Stellaris stores campaigns beneath your user documents or application data directory. Each campaign normally has its own folder containing autosaves and manual `.sav` files.

## Default save folders

| Platform | Folder |
| --- | --- |
| macOS | `~/Documents/Paradox Interactive/Stellaris/save games/` |
| Windows | `Documents\Paradox Interactive\Stellaris\save games\` |
| Linux with Steam | `~/.local/share/Paradox Interactive/Stellaris/save games/` |
| Linux with Flatpak Steam | `~/.var/app/com.valvesoftware.Steam/.local/share/Paradox Interactive/Stellaris/save games/` |

Cloud saves may appear in a Steam userdata directory instead. Stellaris Companion checks the standard candidates, but a custom documents folder, redirected Windows profile, sandbox, or non-Steam install can move them.

## If the Companion cannot find a campaign

1. Save the campaign manually from Stellaris.
2. Search your computer for the newest `.sav` file.
3. In Stellaris Companion, use manual import and select that file.
4. If the folder is protected, grant the app read access when your operating system asks.

Never reorganize or delete the original campaign just to make the Companion see it. Manual import is the safer fallback.

# Use Stellaris with Claude and Codex

> Connect a local AI client to campaign context without uploading raw saves or pasting giant reports.

Source: https://galacticfilingcabinet.com/guides/use-stellaris-with-claude-and-codex/ · Markdown: https://galacticfilingcabinet.com/guides/use-stellaris-with-claude-and-codex/index.md

Stellaris Companion can serve structured campaign context to supported local AI clients through MCP. The client asks for the relevant briefing and reasons in its own chat.

## Before connecting

1. [Install Stellaris Companion](/docs/start-here/install).
2. [Connect a campaign save](/docs/start-here/connect-your-first-save).
3. Verify the newest snapshot in the app.
4. Open **Settings → MCP Relay** and run the health check.

Then follow the client-specific guide for [Claude Desktop](/docs/ai-app-connections/claude-desktop) or [Codex](/docs/ai-app-connections/codex).

## Productive prompts

- “Use Advisor Briefing first. What changed in my economy since the previous snapshot?”
- “Assess whether I can fight this war without collapsing alloy replacement.”
- “Use Chronicle source material to draft this era as a skeptical senate historian.”

Keep the agent's claims inspectable. It should distinguish extracted facts, historical trends, and strategic inference. For Chronicle, ask it to save back only after you approve the draft.

# How to write a Stellaris AAR

> Turn a long campaign into a readable after-action report with a clear point of view and evidence from your save history.

Source: https://galacticfilingcabinet.com/guides/write-stellaris-aar/ · Markdown: https://galacticfilingcabinet.com/guides/write-stellaris-aar/index.md

A good after-action report is not a transcript of every notification. It is a history shaped around decisions, reversals, and consequences.

## Choose the frame

Pick a narrator and a reason the history exists:

- an imperial archive justifying expansion;
- a democratic commission investigating a disastrous war;
- a spiritual chronicle interpreting signs and schisms;
- a machine log measuring deviation from the founding directive;
- an academic history written after the empire's fall.

## Build chapters from change

Use the Companion's Chronicle source material to find clusters of events. A chapter usually needs:

1. a starting condition;
2. a decision or pressure;
3. an irreversible change;
4. a consequence that points to the next era.

Draft in the Companion or a connected AI app. Keep revision in chat until the voice and facts are right, then explicitly ask the client to save the approved passage back.

## Edit for the reader

Preserve specific dates, names, and stakes, but remove repeated bookkeeping. If a battle matters, explain what it changed. If an election matters, show how policy or identity moved afterward.