PuGa

A set of tools and know-how for Claude (Claude Code) to assist in the game Prosperous Universe, usable by humans too. You ask questions in plain language; Claude answers by running the tools in this repo against live market data and your own company data, instead of guessing.

Name origin: Plutonium–gallium alloy (Pu–Ga) is a specialized metallic blend of plutonium and gallium primarily used to stabilize the desirable delta (δ) phase of plutonium at room temperature.

How it is meant to be used

Open Claude Code in this folder. CLAUDE.md is loaded automatically: it tells Claude who the player is, which tools exist, which numbers to trust, and how to answer. Claude also reads empire/PROFILE.md (who you are, how you want answers) if you have one. Then just ask, e.g. "what should I build on Sunday?", "is BHP still worth it?", "simulate my HWP plan". Every tool is also a normal command line script, so you can run them yourself.

Everything the tools print is an estimate from public and personal game data. Prices move; re-run before acting.

Features

Data layer

• Cached clients for the FIO REST API and the PRUNplanner API (public game data, order books, price history, your own sites, storage, production, ships, cash).

Market tools

• price: bid, ask, 7/30-day VWAP, daily volume, supply and demand at every exchange; fill price for a quantity.
• book: order-book ladder with cumulative depth (market-maker orders handled).

Economics engine (puga/econ.py, ported from the PRUNplanner source, which is treated as the source of truth and checked against its own tests and live FIO values)

• Building efficiency: COGC, HQ, experts, faction bonus, fertility, building condition.
• Workforce satisfaction and consumption, extraction rates, production per day, housing optimizer.

Finding opportunities

• scan: ranks every recipe with a depth-aware market model, so it does not recommend recipes whose whole market fits one or two buildings. Fully staffed and understaffed variants, freight cost, HQ/COGC/experts, --min-n filter for real markets, a --planet mode (extraction, fertility, COGC of a specific planet) and a demolish-later cost.
• persistence and history: how long has a margin lasted? Re-prices any opportunity over the exchange history (30/90/180 days), with payback and expected net gain over 7 and 14 days.
• chain: make-versus-buy cost tree with sourcing depth of every input.
• arb (planned) and the legacy prun_scan / prun_cxarb (kept as a baseline, they overstate thin markets).

Your own position

• state: syncs empire/state/company.yaml from FIO: cash, permits, buildings, real production efficiency, storage and ships.
• simulate: a Python replica of the PRUNplanner simulator (workforce, efficiency, material I/O, profit), verified against screenshots of it. Reads a local plan or a saved plan from your account, and reports the real new capex (planned minus already built).
• plan_push: creates, updates and deletes plans in your PRUNplanner account from small YAML files (examples in plans/examples/). Dry run by default; only plans named [PuGa] ... can be written or deleted.

Knowledge for Claude (CLAUDE.md, docs/)

• Verified game mechanics, the market-saturation design, a decision log and a roadmap (docs/). Everything specific to your own empire (profile, state, plans, notes) lives in the gitignored empire/ folder, so this repo can stay public.

Setup

Requires Python 3.12 or newer and git.

git clone <repo-url> PuGa
cd PuGa

# 1. virtual environment
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. keys
cp .env.example .env
chmod 600 .env
$EDITOR .env          # fill in the values below

# 3. optional: the PRUNplanner source used as reference for game mechanics (gitignored)
tools/refresh_refs.sh

# 4. check it works
.venv/bin/python -m pytest
.venv/bin/python tools/price.py BHP --cx AI1

.env

.env is gitignored and never committed. Do not paste keys into chat; edit the file.

Variable	What it is
FIO_USERNAME	your in-game / FIO user name
FIO_REST_KEY	your FIO REST key (used for your own sites, storage, production, ships, cash on rest.fnar.net)
FIO_API_KEY	your FIO API (web) key; separate from the REST key, currently unused
PRUNPLANNER_API_KEY	API key from your PRUNplanner account, sent as Authorization: Api-Key <key>
COMPANY_CODE	your company code (used by tools/state.py for the first sync)
DEFAULT_CX, DEFAULT_REGION	default exchange (AI1 = Antares) and region

Only the public data works without keys (prices, recipes, planets). Your own data needs the FIO extension for the browser client to have uploaded it recently: run tools/state.py sync and check the as_of time.

Usage

.venv/bin/python tools/state.py sync                               # refresh your company state from FIO
.venv/bin/python tools/scan.py --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
.venv/bin/python tools/scan.py --planet ZV-307d --min-n 3          # a specific planet
.venv/bin/python tools/scan.py --min-n 3 --json rows.json && .venv/bin/python tools/persistence.py rows.json
.venv/bin/python tools/chain.py KV --qty 13
.venv/bin/python tools/simulate.py plans/examples/hwp_buildout.yaml --basis vwap30
.venv/bin/python tools/plan_push.py plans/examples/hwp_buildout.yaml # dry run; add --apply to write

Layout

CLAUDE.md      entry point for Claude: rules, tool index, source-of-truth order
docs/          game and toolkit knowledge: mechanics, market model, decisions, roadmap
puga/          library: data clients, market, economics, saturation, simulator
tools/         command line tools
plans/examples/ generic plan specs (also test fixtures)
state/         company.example.yaml, the shape of your synced state
tests/         pytest suite
empire/        (gitignored) YOUR empire: PROFILE.md, state/company.yaml, plans/, docs/ (notes, build plans)
data/          (gitignored) fetched data cache
ref/           (gitignored) PRUNplanner source, read-only reference

The empire/ folder

Game knowledge and generic methods go in docs/; anything about your own bases, cash, decisions or preferences goes in empire/, which is gitignored. tools/state.py sync creates empire/state/company.yaml (on first use set COMPANY_CODE in .env). Add empire/PROFILE.md yourself: your name, company, how you want answers, agreements with Claude.

Not affiliated with Prosperous Universe, FIO or PRUNplanner.