Factorio Local AI Companion

Runs on Windows, macOS, and Linux with either a local Ollama model or the Codex CLI. Node.js 18 or newer is required; there are no npm dependencies.

Quick Start With Ollama

1. Install Factorio 2.1, Node.js 18+, and Ollama.

2. Install and enable the mod as described below.

3. Enable Factorio local RCON with password codex-local.

4. Pull a tool-capable model:

   ollama pull qwen3:8b
   

5. Start the interactive launcher, choose an installed Ollama model, and choose a mode:

   • Windows: double-click scripts\Factorio-Companion-Windows.cmd
   • macOS: double-click scripts/Factorio-Companion-macOS.command
   • Linux: run ./scripts/factorio-companion-linux.sh

The selected model is remembered in config/selected-ollama-model.txt. Then use /codex hello or the overlay inside Factorio. FACTORIO_OLLAMA_MODEL can still override the model for the older direct launch scripts; OLLAMA_HOST changes the Ollama endpoint.

The launcher offers two server modes. Ollama companion is the normal game mode and includes chat, Factorio tools, and in-game replies. Standalone MCP server is only for an external MCP client; because MCP uses standard input/output, it waits silently until such a client connects. Ollama itself does not consume a standalone MCP process, so the Ollama companion calls the same bounded Factorio tool implementations directly.

The Ollama route uses the native /api/chat tool-calling API. It allows at most two read-only Factorio calls and one game-changing call per player message. Construction ghosts are only supposed to be placed after an explicit build/place/design request, and the mod separately enforces its distance and entity-count limits.

Tool Cookbooks

The cookbooks directory contains a Factorio 2.1 tool-selection guide, task recipes, RCON/Lua boundary rules, API semantics, authoritative documentation links, and a naming shortlist. The compact quick reference is loaded into every Ollama and Codex-routed turn so local models know which tool to choose and how to interpret results.

Rivet Agent Prototype

Rivet's identity lives under identity, while the dependency-free durable memory backend lives under backend. It stores structured tasks and facts as atomic JSON projections and preserves task history and conversational evidence as append-only JSONL. Context is rebuilt per turn within a fixed budget; it is not an ever-growing transcript and does not recursively summarize previous summaries. See docs/rivet-memory-architecture.md and docs/rivet-agent-prototype.md.

The agentic harness routes exact commands around the model, chooses narrow context/tool profiles for other turns, supports separate fast and planning Ollama models, preloads models, caps output generation, and records privacy-conscious latency/token telemetry. See docs/rivet-agentic-harness.md.

Visual requests capture a Factorio screenshot, confine and validate the output path, and attach the pixels to a dedicated Ollama vision-model turn. See docs/rivet-vision.md.

Rivet may also register session-scoped exact-match read-only fast tasks. These are validated declarative records, never scripts: one trigger, one allowlisted operation, fixed arguments, and a built-in renderer. See docs/rivet-fast-tasks.md.

MCP Server

The stdio MCP server is mcp/factorio-mcp-server.mjs. It exposes status, stats, nearby scans, item analysis, screenshots, ghost placement, in-game replies, and drone status. Set FACTORIO_RCON_PASSWORD in the MCP server environment.

Portable MCP launchers are included:

• Windows: scripts\start-mcp-windows.cmd
• macOS: scripts/start-mcp-macos.command
• Linux: scripts/start-mcp-linux.sh

The MCP server speaks JSON-RPC over standard input/output, so a terminal that starts it will appear to wait silently. Normally an MCP client launches it and communicates over those streams.

All in-game Codex requests default to low reasoning effort. Each request uses a fresh ephemeral Codex turn, the Factorio MCP tools, and a compact JSON planning note instead of resuming an ever-growing Codex transcript. Override with FACTORIO_CODEX_FAST_REASONING, FACTORIO_CODEX_DEEP_REASONING, or the bridge flags --fast-reasoning and --deep-reasoning.

Phase 1 gives Factorio an in-game Codex panel and a local bridge.

What Works Now

• /codex <message> in Factorio adds the message to the Codex panel.

• A draggable Codex overlay appears near the minimap with a clickable text box and send button.

• The mod exports messages to the platform Factorio data directory under script-output/codex-companion/outbox.jsonl.

• The local bridge tails that file and prints new messages.

• With local RCON enabled, the bridge can send replies back into Factorio:

  /reply Build more green circuits. The factory is hungry.

Install The Mod

Copy or symlink the mod contents into a folder named codex-companion_0.1.0 under:

• Windows: %APPDATA%\Factorio\mods\codex-companion_0.1.0
• macOS: ~/Library/Application Support/factorio/mods/codex-companion_0.1.0
• Linux: ~/.factorio/mods/codex-companion_0.1.0

Then enable codex-companion in mod-list.json or in the Factorio Mods UI.

Enable RCON Replies

Factorio must be restarted after changing this.

Edit Factorio's config/config.ini beneath the platform data directory listed above:

local-rcon-socket=127.0.0.1:27015
local-rcon-password=codex-local

Then launch Factorio and load the save. The portable Ollama launchers are the recommended route. To operate the bridge manually:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local

Inside Factorio:

/codex hello from the factory

Inside the bridge:

/reply Hello engineer. I am in the walls.

Note: RCON replies use Factorio's /silent-command to call the mod's remote interface. Console commands may affect achievements for that save; use this on a save where that tradeoff is acceptable.

Overlay

The overlay is created in player.gui.screen, defaults near the top-right/minimap area, and can be dragged by its title row. Click the text field, type a message, and press Enter or the arrow button to send it to the bridge. The small collapse button hides or shows the message body.

Changes to data.lua styles require a Factorio restart.

Stats And Ghost Building

After Factorio reloads this mod version, the bridge can call read-only stats:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --stats

It can also place construction ghosts without creating blueprints or adding anything to your inventory:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --place-ghosts ./examples/small-power-pole-line.json

Ghost requests are capped at 200 entities and must be within 150 tiles of the target player unless the request explicitly sets allow_far.

Look Before Building

Codex should inspect the area before placing ghosts.

Take a Factorio-rendered screenshot around the target player:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --screenshot-request ./examples/player-wide-screenshot.json

The screenshot is written under:

the platform Factorio data directory under script-output/codex-companion/screenshots.

Scan entities around the target player:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --scan-radius 80

The scan returns JSON with entity counts, resource counts, forces, ghosts, and sample entity positions.

Production Questions

For questions like "why am I low on electronic circuits?", use:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --analyze-item electronic-circuit --analyze-request ./examples/analyze-local-production.json

This returns:

• recipes that produce the item
• upstream ingredients and their recipes
• production and consumption totals
• personal/logistics/chest availability near the player
• local machines crafting the relevant recipes

Codex Marker

Show a visible gold Codex marker in-world:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --marker-request ./examples/gold-codex-marker.json

This is the first safe "drone presence": visible, temporary, and non-physical. A later version can promote it into a constrained builder with inventory and logistics behavior.

Codex Drone Smoke Test

This build includes a real selectable codex-drone entity prototype. It is gold, visible, force-owned, and non-building for now.

Spawn it near the target player:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --spawn-drone-request ./examples/spawn-codex-drone.json

Check status:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --drone-status

Remove it:

node ./bridge/factorio-codex-bridge.mjs --rcon-password codex-local --remove-drone

Live Session Router

The bridge can watch Factorio chat immediately and route each map/session to a stable Codex session registry.

Every new outbox event includes:

• session_id
• surface
• force
• player
• tick

Session state is stored in:

work\factorio-codex-companion\logs\factorio-sessions.json

Safe log-only watcher:

.\bridge\watch-factorio-log.ps1

Immediate Codex CLI watcher:

.\bridge\watch-factorio-codex-exec.ps1

The codex-exec mode creates a fresh ephemeral Codex CLI turn, writes compact continuity and the last answer under logs, and sends the reply back into Factorio through RCON.

Current limitation: this routes into persisted Codex CLI sessions, not a visible desktop task in the Codex sidebar. The bridge has registry fields for desktop threadId, but desktop task creation/message routing needs a supported app-server adapter before an external Node process can create and send to Codex desktop tasks directly.