tgoti 0.0.1

Terminal Tamagotchi for stocks — each pet is a real or simulated Alpaca position

tgoti

Terminal Tamagotchi for stocks. Each pet IS a real (or simulated) Alpaca position; HP tracks unrealized P&L, feeding buys more of the symbol, pets age only during NYSE market hours.

 ████████  ██████  ██████  ████████  ██
    ██     ██      ██  ██     ██     ██
    ██     ██ ███  ██  ██     ██     ██
    ██     ██  ██  ██  ██     ██     ██
    ██     ██████  ██████     ██     ██
            stockpets

Install

git clone [e-mail]:joeltco/tgoti.git
cd tgoti
pip install -e .

Python 3.11+. Optional Alpaca SDK for paper/live: pip install -e .[alpaca].

Docker

docker build -t tgoti .
docker run -it --rm tgoti            # play in sandbox mode
docker run --rm tgoti --list-saves   # headless CLI ops

Run

tgoti                  # default: sandbox
tgoti --mode paper     # Alpaca paper account
tgoti --mode live      # real money, $100/pet cap

Alpaca paper/live needs credentials at ~/.config/alpaca-tui/credentials.yaml:

paper:
  api_key: PK...
  secret_key: ...
live:
  api_key: AK...
  secret_key: ...

What it does

• 3 modes: sandbox (local RNG, fast-forwards while you're away), paper (Alpaca paper), live (real money, $100/pet cap).
• 8 biomes with themed ticker pools: meadow (blue chips), stormy (momentum), highlands (crypto), tide_pools (ETFs), volcanic (energy), frostlands (healthcare), ruins (legacy/value), forest (clean energy).
• 5-element type chart: Fire → Ice → Storm → Earth → Spirit → Fire. Pet element = biome element. Matchup multiplies battle damage ×1.5 / ×1.0 / ×0.67.
• 3-tier monsters weighted by pet stage. Eggs face mostly Tier 1; Legendaries face mostly Tier 3. 5% chance per battle of a boss roll (one boss per biome).
• 5 evolution stages: Egg (0.1pd) → Baby → Junior (13pd) → Adult (32pd) → Legendary (100pd + positive P&L). "pd" = pet-day = 1 hour of NYSE market time. Eggs hatch fast (~6 min market time) and are inert until they do.
• Death conditions: drawdown beyond config.DEATH_DRAWDOWN_PCT closes the position and graveyards the pet; manual release does the same with reason='released by player'.

See docs/gameplay.md for the full rules + keybindings.

CLI

The game is a TUI but every read-only operation has a CLI flag. A few:

tgoti --list-saves                  # all saves, alive/dead/awake
tgoti --stats 3                     # plain-text stats for save #3
tgoti --pets 3 --sort hp            # alive pets, lowest-HP first
tgoti --events 12 --kind fed        # event log for pet #12
tgoti --search META                 # find pets by symbol across saves
tgoti --slayers --json              # pets with 3+ boss kills
tgoti --champions --top 10          # longest-lived across all saves
tgoti --tally --watch               # live cross-save summary
tgoti --doctor --json               # db + settings integrity check
tgoti --backup ~/tgoti-backup       # dump every save to JSON

--watch works with --stats / --pets / --events / --leaderboard / --tally / --list-saves. --json works wherever there's tabular output.

tgoti --help lists everything.

Development

pip install -e .[dev]

ruff check
mypy
bandit -c pyproject.toml -r tgoti/
pytest -q

All four run in CI on every push and PR (Python 3.11 + 3.12).

See CONTRIBUTING.md for project structure, the sprite pipeline, and the test-isolation rule (every test must inject db_path and settings_path — see existing _fresh_app() helpers).

License

MIT (see LICENSE once added). Sprite pack (tools/sprite_sources/tiny-creatures/) is CC0 from the original asset author — see License.txt in that directory.