What is agent-desmume?

pakoito/agent-desmume — explained in plain English

Analysis updated 2026-05-18

★ 0PythonAudience · developerComplexity · 4/5LicenseSetup · hard

Mindmap

mindmap
  root((agent-desmume))
    What it does
      Headless DS Emulation
      Unix Socket CLI
      Persistent Daemon
    Tech stack
      Python
      Cython
      DeSmuME Fork
    Capabilities
      Frame Stepping
      Memory Read Write
      Breakpoints
      Screenshots
    Use cases
      Fan Translation Testing
      LLM Agent Control
      Reverse Engineering
    Limits
      No Microphone
      No Realtime Playback

mindmap root((agent-desmume)) What it does Headless DS Emulation Unix Socket CLI Persistent Daemon Tech stack Python Cython DeSmuME Fork Capabilities Frame Stepping Memory Read Write Breakpoints Screenshots Use cases Fan Translation Testing LLM Agent Control Reverse Engineering Limits No Microphone No Realtime Playback

What do people build with it?

USE CASE 1

Automate testing of fan-translated Nintendo DS ROMs by scripting menu navigation and screenshot checks.

USE CASE 2

Give an LLM agent a programmatic way to boot a DS ROM, read memory, and take screenshots without a window manager.

USE CASE 3

Set memory watchpoints and code breakpoints to reverse engineer how a DS game behaves at runtime.

USE CASE 4

Record and replay deterministic frame-perfect test runs for regression testing a ROM.

What is it built with?

PythonCythonDeSmuMEUnix Socket

How does it compare?

	pakoito/agent-desmume	0xhassaan/nn-from-scratch	3ks/embedoc
Stars	0	0	—
Language	Python	Python	Python
Last pushed	—	—	2023-06-08
Maintenance	—	—	Dormant
Setup difficulty	hard	moderate	hard
Complexity	4/5	4/5	1/5
Audience	developer	developer	developer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1h+

First install takes about 9 minutes because it compiles DeSmuME from source, several system build dependencies must be installed first.

GPL-3.0-or-later means you can use and modify the code freely, but any distributed derivative work must also be open source under the same license.

So what is it?

agent-desmume is a command-line tool and background daemon that lets scripts or AI agents control a Nintendo DS emulator without a graphical display. It is built for automated testing, such as checking fan translations of games or navigating game menus automatically, and for giving large language model agents a programmatic way to interact with DS ROM files. The tool wraps DeSmuME, a Nintendo DS emulator, through a Python binding layer. A persistent daemon starts in the background and keeps the emulator running across multiple commands. The CLI sends instructions to the daemon over a Unix socket: boot a ROM, step a specific number of frames, take a screenshot of either or both screens, press buttons, tap the touchscreen, save or load game states, import battery saves, and read or write any memory address. Commands return JSON output when requested, making them easy to parse from automation scripts or AI tool calls. The tool supports frame-perfect deterministic stepping rather than real-time playback, which is suited for testing and repeatability. It also supports ARM processor register access, code breakpoints, memory watchpoints, and GPU layer toggling for isolating text in screenshots. Multiple parallel sessions are supported via named session identifiers. It integrates optionally with Claude Code as a skill, so AI agents can discover and use its commands automatically. The tech stack is Python with Cython bindings through a fork of py-desmume. The underlying DeSmuME C library is compiled from source during installation. The license is GPL-3.0+, inherited from DeSmuME and py-desmume.

Copy-paste prompts

Prompt 1

Show me how to install agent-desmume and boot a ROM with the CLI, then step 600 frames and take a screenshot.

Prompt 2

Write a Python script that uses agent-desmume's JSON output to detect when a specific screen appears, then presses a button.

Prompt 3

Explain how to set a memory watchpoint with agent-desmume to find the address that stores a game's in-game currency.

Prompt 4

Help me register agent-desmume as a Claude Code skill so an agent can drive a DS emulator automatically.

Prompt 5

How do I run two parallel agent-desmume sessions to test two different save states at once?

Frequently asked questions