# geohot/pi_plays_pokemon architecture

> Architecture diagram of the GitHub repository geohot/pi_plays_pokemon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geohot/pi_plays_pokemon
- Repository: https://github.com/geohot/pi_plays_pokemon

## Overview

This repository is a lightweight game-playing harness: pi’s model observes screenshots, issues button presses, and judges completion through the extension’s tools. The emulator sidecar owns gameplay state, campaign resumption, run evidence, and the live web UI. An optional stream mirror forwards pi’s reasoning and tool results to that UI. The README documents these capabilities; the sampled source is partial, so uncertain internal wiring is omitted.

Main entry points: [`emu.py`](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py) (HTTP sidecar), [`.pi/extensions/game.ts`](https://github.com/geohot/pi_plays_pokemon/blob/main/.pi/extensions/game.ts) (Game tools), [`stream.py`](https://github.com/geohot/pi_plays_pokemon/blob/main/stream.py) (Event mirror), [`roms`](https://github.com/geohot/pi_plays_pokemon/tree/main/roms) (Game ROM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent Interface"]
  node_extension["Game tools<br/>[game.ts]"]
  node_prompt["Game prompt<br/>[SYSTEM.md]"]
end

subgraph group_game["Game Runtime"]
  node_sidecar["HTTP sidecar<br/>[emu.py]"]
  node_emulator["Game Boy emulator<br/>[emu.py]"]
end

subgraph group_runs["Run State"]
  node_campaign[("Campaign state<br/>[emu.py]")]
  node_runfiles[("Run evidence<br/>[emu.py]")]
end

subgraph group_observe["Live Observability"]
  node_stream["Event mirror<br/>[stream.py]"]
  node_ui["Live web UI<br/>[emu.py]"]
end

node_model(("Pi model"))
node_pi(("Pi agent"))
node_rom["Game ROM"]
node_browser(("Web UI viewer"))

node_pi -->|"loads tools"| node_extension
node_pi -->|"uses prompt"| node_prompt
node_model -->|"calls tools"| node_extension
node_extension -->|"HTTP requests"| node_sidecar
node_sidecar -->|"controls"| node_emulator
node_rom -->|"loads ROM"| node_emulator
node_emulator -->|"saves state"| node_campaign
node_campaign -->|"resumes state"| node_emulator
node_sidecar -->|"writes evidence"| node_runfiles
node_pi -.->|"JSON events"| node_stream
node_stream -.->|"posts feed"| node_sidecar
node_browser -->|"opens UI"| node_ui
node_ui -->|"requests status"| node_sidecar
node_sidecar -->|"serves screen and logs"| node_ui

click node_extension "https://github.com/geohot/pi_plays_pokemon/blob/main/.pi/extensions/game.ts"
click node_prompt "https://github.com/geohot/pi_plays_pokemon/blob/main/.pi/SYSTEM.md"
click node_sidecar "https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py"
click node_emulator "https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py"
click node_rom "https://github.com/geohot/pi_plays_pokemon/tree/main/roms"
click node_campaign "https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py"
click node_runfiles "https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py"
click node_stream "https://github.com/geohot/pi_plays_pokemon/blob/main/stream.py"
click node_ui "https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_prompt,node_browser toneBlue
class node_sidecar,node_emulator toneAmber
class node_campaign,node_runfiles toneMint
class node_stream,node_ui toneRose
class node_model,node_pi toneIndigo
class node_rom toneTeal
```

## Components

### Agent Interface

- [Game tools](https://github.com/geohot/pi_plays_pokemon/blob/main/.pi/extensions/game.ts): `.pi/extensions/game.ts`
- [Game prompt](https://github.com/geohot/pi_plays_pokemon/blob/main/.pi/SYSTEM.md): `.pi/SYSTEM.md`

### Game Runtime

- [HTTP sidecar](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py): `emu.py`
- [Game Boy emulator](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py): `emu.py`

### Run State

- [Campaign state](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py): `emu.py`
- [Run evidence](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py): `emu.py`

### Live Observability

- [Event mirror](https://github.com/geohot/pi_plays_pokemon/blob/main/stream.py): `stream.py`
- [Live web UI](https://github.com/geohot/pi_plays_pokemon/blob/main/emu.py): `emu.py`

### Other components

- **Pi model**
- **Pi agent**
- [Game ROM](https://github.com/geohot/pi_plays_pokemon/tree/main/roms): `roms`
- **Web UI viewer**

## Connections

- Pi agent → Game tools: loads tools
- Pi agent → Game prompt: uses prompt
- Pi model → Game tools: calls tools
- Game tools → HTTP sidecar: HTTP requests
- HTTP sidecar → Game Boy emulator: controls
- Game ROM → Game Boy emulator: loads ROM
- Game Boy emulator → Campaign state: saves state
- Campaign state → Game Boy emulator: resumes state
- HTTP sidecar → Run evidence: writes evidence
- Pi agent → Event mirror: JSON events
- Event mirror → HTTP sidecar: posts feed
- Web UI viewer → Live web UI: opens UI
- Live web UI → HTTP sidecar: requests status
- HTTP sidecar → Live web UI: serves screen and logs