Factorio Codex Coach

See the whole factory. Fix the right problem.

Factorio Codex Coach is a second set of eyes and hands for ambitious Factorio 2.1 saves. It watches the running factory, finds problems that are difficult to see from one screen, recommends the next useful action, and can handle selected maintenance work while the player keeps designing and expanding.

It is useful when a save has become large enough that the real challenge is no longer placing one more assembler. The coach can help answer:

• Why has science stopped?
• Is the factory short on power, materials, machines, or logistics throughput?
• Which planet, platform, or production chain needs attention next?
• Are modules and high-quality buildings being used where they matter?
• Are robots wasting time, defenses degrading, or ships waiting indefinitely?
• What did the automation change, and why?

The goal is not to play Factorio instead of the player. The goal is to remove repetitive maintenance, expose hidden bottlenecks, and keep a complicated save legible without silently rewriting player-authored designs.

What Players Get

• A live factory cockpit. The dashboard combines the current progression phase, next action, science, power, logistics, critical material flows, defense, robots, planets, platforms, recent coach actions, and performance.
• Practical advice from current game state. Recommendations come from live RCON observations and cached state, not a generic Factorio checklist.
• Optional hands-on assistance. The maintained assisted profile can perform bounded module placement and upgrades, assembler upgrades, quality-stock deployment, depleted-miner cleanup, beacon placement, and other repetitive jobs.
• Conservative automation. Policies preserve player request sections and installed module families. Mutations are paced through runtime budgets, typed plans, safety gates, and audit logs.
• Long-save operational support. The coach can pause an empty server, monitor expensive scans, retain cursors between restarts, and show what its automation is doing instead of becoming another source of lag.

Dashboard

The dashboard works as a full-screen second-monitor cockpit or a dense 360-420px side panel beside Factorio. It is local HTML backed by the coach's observed-state cache, so opening it does not trigger additional game scans. It can also be viewed from a phone through Tailscale. Fixed command buttons can request safe reports such as power, robot charging, recycling, scan status, or pause/resume.

Python First, LLM Optional

Most of the coach is deterministic Python:

Python coach	Optional LLM
Observes Factorio through RCON and the companion event stream	Answers genuinely open-ended /codex ask ... questions
Maintains a timestamped SQLite/file state cache	Can perform an explicitly requested model-backed priority review
Diagnoses power, science, factory, logistics, robot, combat, and platform state	Adds conversational judgment when fixed policy and reports are insufficient
Builds plans, applies opted-in automation, writes audit logs, and renders the dashboard	Runs through the local Codex CLI only when model-backed requests are enabled
Uses no model tokens	Uses tokens only for the individual request

The normal observer and the maintained assisted profile make zero LLM calls. Routine reports, dashboard updates, pause/resume, strategy phases, and scheduled deep reviews are Python and do not consume model tokens. Despite the name, the scheduled deep review is deterministic.

Model use is opt-in through --answer-requests. Even then, recognized status questions are answered from cached state without a model. An open-ended question or an explicit model-backed deep review invokes Codex only while a player is connected and the game is unpaused. The coach is therefore not a background token stream; model cost is limited to the questions the player chooses to ask and varies with the selected model.

How A Player Uses It

1. Host an existing save with local RCON and join it from the normal Factorio client.
2. Run the coach as a read-only observer or start the maintained assisted profile for conservative automation.
3. Keep the dashboard beside the game or open it from another device.
4. Play Factorio normally. Use the dashboard, in-game status, and optional /codex ask ... questions when a decision or diagnosis is needed.

Single-player Or Multiplayer

The coach operates against one hosted Factorio save, not one particular player. That makes the same architecture useful for a private solo campaign or a shared multiplayer factory.

Single-player: host the save locally with scripts/host-rcon.sh, then join your own server from the normal Factorio client. Factorio presents this as a multiplayer connection, but the game can remain private and have only one player. This gives the coach a stable RCON connection, lets the dashboard keep observing the save, and allows --pause-when-empty to save resources when you leave. No external server or public listing is required.

Multiplayer: run one coach beside the shared headless server. Every player sees the same factory state, advice, map tags, and opted-in automation; players do not each need a separate coach process. The companion records which player submitted an in-game /codex ask ... request so the response can return to the game. With --pause-when-empty, the server pauses only after the last player leaves and resumes when someone reconnects.

RCON remains a server-side control channel and should stay bound to localhost. Players join through Factorio's normal game port and never need the RCON password. If the companion mod is enabled, clients and server must load the same companion version just as they would for any other Factorio mod.

Because assisted automation changes the shared factory, multiplayer groups should agree on which mutating policies are enabled. Observer mode and the read-only dashboard are suitable when the group wants diagnosis without automatic construction or upgrades.

The optional companion mod provides the richest experience: in-game /codex commands, event deltas, and the complete live dashboard pipeline. Direct no-plugin RCON observation is also supported for saves where a minimal mod set matters.

The coach is game-agnostic. It can observe ordinary or modded saves, but it does not contain policy, telemetry, launch profiles, or prototype knowledge for any particular content mod.

Repository Map

Path	Purpose
mod/factorio_codex_companion_0.1.0/	Optional /codex and delta-export bridge
bridge/	Observations, policies, planners, appliers, state, and dashboard server
dashboard/	Local HTML/CSS/JavaScript dashboard
scripts/	Installers, launchers, validators, and operational helpers
tests/	Unit, fixture, policy, launcher, and contract tests
feature_specs/	Implemented and proposed subsystem specifications
RUNBOOK.md	Live-server, dashboard, and recovery procedures
factorio-coach-skill.md	Standalone onboarding instructions for another agent

Requirements

• Factorio 2.1 with Space Age
• Python 3.11 or newer
• jq
• tmux for the documented detached workflow
• Pillow for the complete test suite
• Playwright only for optional dashboard screenshot validation

The scripts default to the macOS Steam installation. Override paths with:

export FACTORIO_BINARY='/path/to/factorio'
export FACTORIO_READ_DATA='/path/to/factorio/data'
export FACTORIO_MODS_DIR='/path/to/factorio/mods'
export FACTORIO_SAVES_DIR='/path/to/factorio/saves'

Clone And Validate

git clone git@github.com:lukec/factorio-codex-coach.git
cd factorio-codex-coach

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements-dev.txt
python3 -m unittest discover tests

Install The Companion

scripts/install-mod.sh

The companion mod is optional. Direct no-plugin RCON mode is supported when a minimal mod set matters, but that mode uses Factorio scripting commands and should not be presented as achievement-preserving.

Run

Keep the RCON password in the environment:

read -r -s FACTORIO_RCON_PASSWORD
export FACTORIO_RCON_PASSWORD

Start an existing save:

scripts/host-rcon.sh '<save name>.zip'

Start the conservative observer:

python3 -u bridge/watch_factorio.py \
  --interval 60 --radius 192 --pause-when-empty

Start the maintained assisted profile:

scripts/start-assisted-coach.sh --session assisted-01

The exact tmux workflow, safe save/restart procedure, no-plugin mode, dashboard commands, and RCON checks are in RUNBOOK.md.

Architecture

Read COACH_ARCHITECTURE.md before changing coach behavior. New automation should separate observation, pure planning, scheduling/risk gates, thin appliers, and persistence. Every recurring mutation should be explainable from planned actions and mutation logs.

This is a private repository. No public license is granted.