# 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](https://ollama.com/).
2. Install and enable the mod as described below.
3. Enable Factorio local RCON with password `codex-local`.
4. Pull a tool-capable model:

   ```sh
   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:

```ini
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:

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

Inside Factorio:

```text
/codex hello from the factory
```

Inside the bridge:

```text
/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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

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

Check status:

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

Remove it:

```sh
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:

```powershell
.\bridge\watch-factorio-log.ps1
```

Immediate Codex CLI watcher:

```powershell
.\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.