pokemon-agent: official Nous Research repo for Hermes Agent

Headless Pokemon emulator with a REST API and live dashboard that lets Hermes Agent or any LLM agent play

What pokemon-agent does

The server wraps an emulator, a memory reader and a game-state parser behind FastAPI. Game Boy titles (Pokemon Red and Blue) run on PyBoy and GBA titles (FireRed) run on PyGBA, with no display server needed. Endpoints include GET /state, POST /action and GET /screenshot. RAM is parsed into JSON covering party, bag, badges, map, battle, dialog and collision grid, and a RAM-derived ASCII collision map plus a labelled grid screenshot overlay let an agent navigate from walkability data instead of guessing from pixels.

Game sessions bind a Hermes session id, emulator save-states, objectives, milestones and stats together, so loading a game resumes the run along with its Hermes memory. In autopilot mode a second process, pokemon-agent play, invokes the hermes CLI each turn. The optional Field Log dashboard shows the agent's reasoning stream, a live grid map, objectives, a stuck meter, a blackout counter and a milestone timeline.

Key features

Headless Game Boy and GBA emulation through PyBoy and PyGBA
REST endpoints for state, actions and screenshots, plus a WebSocket event stream
RAM-derived collision map and labelled grid screenshot for navigation
Named game sessions that tie save-states to a Hermes session
Autopilot driver that plays through the hermes CLI
Optional Field Log dashboard with reasoning stream and milestone timeline

When to use it

Let a Hermes Agent play Pokemon Red unattended and resume the run later
Test how an LLM agent handles long-horizon navigation and battle decisions
Watch an agent's reasoning and progress on a live dashboard

Who it is for: Developers who want to run or evaluate AI agents on a game through a simple HTTP API.

How it fits with Hermes Agent

Published under the NousResearch organization; the autopilot uses a real Hermes Agent session as the brain, and the API also works with Claude Code, Codex or custom agents.

How to install pokemon-agent

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

pip install pokemon-agent pyboy
pip install pokemon-agent[dashboard] pyboy
pokemon-agent serve --rom path/to/pokemon_red.gb
pokemon-agent play --port 8765

Requirements: Your own game ROM file, PyBoy for Game Boy games, and the hermes CLI on PATH for the autopilot.

Note: The package does not include game ROMs, so you must supply your own.

FAQ

What is pokemon-agent?

pokemon-agent is a package that runs Pokemon games headlessly and lets an AI agent play them over a REST API. It includes a WebSocket stream and an optional live dashboard.

Does pokemon-agent work with Hermes Agent?

Yes. The pokemon-agent play command runs an autopilot where each turn invokes the hermes CLI, so a real Hermes session makes the decisions. Claude Code, Codex and custom agents can use the API too.

Is pokemon-agent free and open source?

Yes. The repository is published under the MIT license. You must provide your own ROM file, because the package includes no game ROMs.