five-borough-burn 0.1.0

AI-driven NYC terminal hustler sim.

Five Borough Burn

Five Borough Burn is a terminal-first NYC hustler sim with a live burner-phone layer.

The game uses your local Codex CLI session as the narrative engine. That means:

• the run setup can change every playthrough
• contacts can have different names, voices, districts, and hooks each run
• live burner replies, city wire updates, and street pulse events can be generated on demand

Requirements

• Python 3.11+
• a terminal with curses support
• the codex CLI installed and already authenticated
• a readable Codex auth file at ~/.codex/auth.json

Install

From the repo:

pip install .

If you want to host online multiplayer rooms too:

pip install ".[online]"

Then launch:

five-borough-burn

You can still run from source if you want:

python main.py

If a minimal Termux Python cannot build the package offline, unzip the source release and run python main.py directly, or install setuptools first and rerun pip install ..

Useful Commands

Smoke test:

python main.py --smoke

Refresh the cached dialog pack:

python main.py --refresh-dialog-pack

Terminal multiplayer client:

five-borough-burn-online --server http://127.0.0.1:8000

Terminal multiplayer room server:

five-borough-burn-roomd --host 127.0.0.1 --port 8000

Controls

• t travel
• b buy
• s sell
• l borrow or repay
• u upgrade stash
• m burner phone
• i intel
• ? help
• q quit

Runtime Data

The installed game writes runtime data to:

~/.five-borough-burn/

That folder holds:

• highscores
• dialog cache
• multiplayer session resume data

You can override it with:

FBB_HOME=/some/path five-borough-burn

Release Build

Create distributable source archives with:

python tools/build_release.py

That script:

• runs the smoke test first
• creates source .zip and .tar.gz bundles in dist/
• writes SHA256SUMS.txt
• builds a wheel and sdist too if the build module is installed locally

If you want wheel builds as well:

pip install build
python tools/build_release.py

Publish

Package metadata lives in pyproject.toml, so standard Python publishing works:

python -m build
python -m twine upload dist/*

build and twine are not bundled with this repo by default.

For automated publishes, the repo also includes GitHub Actions trusted-publishing workflow config at .github/workflows/release.yml. Once a PyPI account/project is configured to trust B11-Health/five-borough-burn and that workflow file, future GitHub releases can publish to PyPI without storing a long-lived API token.