Skip to content
Back to search

Geargrafx

PC Engine / TurboGrafx-16 / SuperGrafx / CD-ROM² / LD-ROM² emulator and debugger with embedded MCP server for macOS, Windows, Linux, BSD and RetroArch.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/drhelius/Geargrafx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/drhelius/Geargrafx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/drhelius--geargrafx/badge.svg)](/listings/drhelius--geargrafx)

HTML

<a href="/listings/drhelius--geargrafx"><img src="/api/listings/drhelius--geargrafx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 305 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Geargrafx
  2. [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/drhelius/Geargrafx/geargrafx.yml)](https://github.com/drhelius/Geargrafx/actions/workflows/geargrafx.yml)
  3. [![GitHub Releases)](https://img.shields.io/github/v/tag/drhelius/Geargrafx?label=version)](https://github.com/drhelius/Geargrafx/releases)
  4. [![commits)](https://img.shields.io/github/commit-activity/t/drhelius/Geargrafx)](https://github.com/drhelius/Geargrafx/commits/main)
  5. [![GitHub contributors](https://img.shields.io/github/contributors/drhelius/Geargrafx)](https://github.com/drhelius/Geargrafx/graphs/contributors)
  6. [![GitHub Sponsors](https://img.shields.io/github/sponsors/drhelius)](https://github.com/sponsors/drhelius)
  7. [![License](https://img.shields.io/github/license/drhelius/Geargrafx)](https://github.com/drhelius/Geargrafx/blob/main/LICENSE)
  8. [![Twitter Follow](https://img.shields.io/twitter/follow/drhelius)](https://x.com/drhelius)
  9. Geargrafx is a very accurate, cross-platform TurboGrafx-16 / PC Engine / SuperGrafx / CD-ROM² / LD-ROM² emulator written in C++ that runs on Windows, macOS, Linux, BSD and RetroArch, with an embedded MCP server for AI debugging and development.
  10. This is an open source project with its ongoing development made possible thanks to the support by these awesome [backers](backers.md). If you find it useful, please consider [sponsoring](https://github.com/sponsors/drhelius).
  11. Don't hesitate to report bugs or ask for new features by [opening an issue](https://github.com/drhelius/Geargrafx/issues).
  12. <img src="http://www.geardome.com/files/geargrafx/geargrafx_debug_02.png">
  13. ## Downloads
  14. <table>
  15. <thead>
  16. <tr>
  17. <th>Platform</th>
  18. <th>Architecture</th>
  19. <th>Download Link</th>
  20. </tr>
  21. </thead>
  22. <tbody>
  23. <tr>
  24. <td rowspan="2"><strong>Windows</strong></td>
  25. <td>Desktop x64</td>
  26. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-windows-x64.zip">Geargrafx-1.8.8-desktop-windows-x64.zip</a></td>
  27. </tr>
  28. <tr>
  29. <td>Desktop ARM64</td>
  30. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-windows-arm64.zip">Geargrafx-1.8.8-desktop-windows-arm64.zip</a></td>
  31. </tr>
  32. <tr>
  33. <td rowspan="3"><strong>macOS</strong></td>
  34. <td>Homebrew</td>
  35. <td><code>brew install --cask drhelius/geardome/geargrafx</code></td>
  36. </tr>
  37. <tr>
  38. <td>Desktop Apple Silicon</td>
  39. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-macos-arm64.zip">Geargrafx-1.8.8-desktop-macos-arm64.zip</a></td>
  40. </tr>
  41. <tr>
  42. <td>Desktop Intel</td>
  43. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-macos-intel.zip">Geargrafx-1.8.8-desktop-macos-intel.zip</a></td>
  44. </tr>
  45. <tr>
  46. <td rowspan="6"><strong>Linux</strong></td>
  47. <td>Ubuntu PPA</td>
  48. <td><a href="https://github.com/drhelius/ppa-geardome">drhelius/ppa-geardome</a></td>
  49. </tr>
  50. <tr>
  51. <td>Fedora RPM</td>
  52. <td><a href="https://github.com/drhelius/rpm-geardome">drhelius/rpm-geardome</a></td>
  53. </tr>
  54. <tr>
  55. <td>Desktop Ubuntu 26.04 x64</td>
  56. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-ubuntu26.04-x64.zip">Geargrafx-1.8.8-desktop-ubuntu26.04-x64.zip</a></td>
  57. </tr>
  58. <tr>
  59. <td>Desktop Ubuntu 26.04 ARM64</td>
  60. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-ubuntu26.04-arm64.zip">Geargrafx-1.8.8-desktop-ubuntu26.04-arm64.zip</a></td>
  61. </tr>
  62. <tr>
  63. <td>Desktop Ubuntu 24.04 x64</td>
  64. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-ubuntu24.04-x64.zip">Geargrafx-1.8.8-desktop-ubuntu24.04-x64.zip</a></td>
  65. </tr>
  66. <tr>
  67. <td>Desktop Ubuntu 24.04 ARM64</td>
  68. <td><a href="https://github.com/drhelius/Geargrafx/releases/download/1.8.8/Geargrafx-1.8.8-desktop-ubuntu24.04-arm64.zip">Geargrafx-1.8.8-desktop-ubuntu24.04-arm64.zip</a></td>
  69. </tr>
  70. <tr>
  71. <td><strong>MCPB</strong></td>
  72. <td>All platforms</td>
  73. <td><a href="MCP_README.md">MCP Readme</a></td>
  74. </tr>
  75. <tr>
  76. <td><strong>RetroArch</strong></td>
  77. <td>All platforms</td>
  78. <td><a href="https://docs.libretro.com/library/geargrafx/">Libretro core documentation</a></td>
  79. </tr>
  80. <tr>
  81. <td><strong>Dev Builds</strong></td>
  82. <td>All platforms</td>
  83. <td><a href="https://github.com/drhelius/Geargrafx/actions/workflows/geargrafx.yml">GitHub Actions</a></td>
  84. </tr>
  85. </tbody>
  86. </table>
  87. **Notes:**
  88. - **Windows**: May need [Visual C++ Redistributable](https://go.microsoft.com/fwlink/?LinkId=746572) and [OpenGL Compatibility Pack](https://apps.microsoft.com/detail/9nqpsl29bfff)
  89. - **Homebrew**: If Homebrew asks you to trust the third-party tap, run `brew trust --tap drhelius/geardome`
  90. - **Linux**: May need `libsdl3`
  91. ## Features
  92. - Accurate emulation supporting the entire HuCard PCE / SGX catalog.
  93. - Support for CD-ROM², Super CD-ROM² and Arcade CD-ROM² systems.
  94. - NEC LaserActive LD-ROM² support through MMI images.
  95. - Save states with preview and rewind support.
  96. - Run-ahead support to reduce input latency.
  97. - Backup RAM and Memory Base 128 support.
  98. - Cheat support for `AAAAAA:VV` codes, with RetroArch `.cht` import.
  99. - TurboLink multiplayer for two emulator instances on the same machine.
  100. - Multi Tap (up to 5 players).
  101. - Standard Gamepad (2 buttons), Avenue Pad 3 (3 buttons, auto-configured based on game), Avenue Pad 6 (6 buttons) and Mouse.
  102. - Adjustable scanline count (224p, 240p or manual).
  103. - RGB or Composite color output with optional LPF filter.
  104. - Compressed ROM and CD image support (pce, sgx, cue, zip, chd and mmi).
  105. - Support for playing physical CD-ROM discs.
  106. - Music ROM support: HES.
  107. - VGM recorder.
  108. - Internal database for automatic ROM detection and hardware selection if `Auto` options are selected.
  109. - Supported platforms (standalone): Windows, Linux, BSD and macOS.
  110. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, webOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX.
  111. - Full debugger with just-in-time disassembler, CPU breakpoints, memory access breakpoints, code navigation (goto address, JP JR and JSR double clicking), debug symbols, automatic labels, memory editor, PSG inspector and video viewer including registers, tiles, sprites, backgrounds, CD-ROM sub-systems and both VDCs in SuperGrafx mode.
  112. - MCP server for AI-assisted debugging with Claude Code, Codex and similar, exposing tools for execution control, memory inspection, hardware status, rewind and more.
  113. - Windows, Linux and macOS *Portable Mode*.
  114. - [Programmable Shader Chain](platforms/shared/desktop/shaders/README.md).
  115. - ROM loading from the command line by adding the ROM path as an argument.
  116. - ROM loading using drag & drop.
  117. - Support for modern game controllers through [gamecontrollerdb.txt](https://github.com/mdqinc/SDL_GameControllerDB) file located in the same directory as the application binary.
  118. ## Tips
  119. ### Basic Usage
  120. - **BIOS**: Geargrafx requires a BIOS to run CD-ROM games. It is possible to load any BIOS but the System Card 3.0 with md5 `38179df8f4ac870017db21ebcbf53114` is recommended.
  121. - **CD-ROM Images**: Geargrafx supports `chd`, zipped and unzipped `cue/bin`, `cue/img` and `cue/iso` images. CUE audio tracks can use raw BIN, compatible WAV (44100 Hz, 16-bit, stereo) or Ogg Vorbis (44100 Hz, stereo) files. MP3 audio tracks are not supported.
  122. - **LaserActive Images**: Geargrafx supports NEC LD-ROM² `.mmi` images. A Japanese PAC-N1/PCE-LP1 or US PAC-N10 BIOS is required. Change disc sides through **Geargrafx → MMI Media** or libretro disk controls. Desktop rewind and run-ahead are disabled for LaserActive.
  123. - **Mouse Cursor**: Automatically hides when hovering over the main output window or when Main Menu is disabled.
  124. - **Portable Mode**: Run with `--portable`, or create an empty file named `portable.ini` in the same directory as the application binary. On macOS, place the file next to the `.app` bundle.
  125. - **Cheats**: Open **Emulator → Cheats...** to enter codes or import a RetroArch `.cht` file. Codes use the `AAAAAA:VV` format with a physical address, for example `1F0DB1:09` writes `$09` to work RAM `$0DB1`. Join several codes with `+`.
  126. ### Debugging Features
  127. - **Docking Windows**: In debug mode, you can dock windows together by pressing SHIFT and dragging a window onto another.
  128. - **Multi-viewport**: In Windows or macOS, you can enable "multi-viewport" in the debug menu. You must restart the emulator for the change to take effect. Once enabled, you can drag debugger windows outside the main window.
  129. - **Single Instance**: You can enable "Single Instance" in the `Emulator` menu. When enabled, opening a ROM while another instance is running will send the ROM to the running instance instead of starting a new one.
  130. - **Debug Symbols**: The emulator automatically tries to load a symbol file when loading a ROM (.sym, .lbl, .noi). For example, for `path_to_rom_file.rom` it tries to load `path_to_rom_file.sym`. You can also load symbol files using the GUI or the CLI. It supports PCEAS (old and new format), wla-dx and vasm file formats.
  131. ### Command Line Usage
  132. ```
  133. geargrafx [options] [game_file] [symbol_file]
  134. Arguments:
  135. [game_file] Accepts ROMs (.pce, .sgx, .hes), CUE (.cue), CHD (.chd), MMI (.mmi) or ZIP (.zip)
  136. [symbol_file] Optional symbol file for debugging
  137. Options:
  138. -f, --fullscreen Start in fullscreen mode
  139. -w, --windowed Start in windowed mode with menu visible
  140. --load-state SLOT Load save state slot 1-5, or a state file, once the media is loaded
  141. --mcp-stdio Auto-start MCP server with stdio transport
  142. --mcp-http Auto-start MCP server with HTTP transport
  143. --mcp-router Enable compact MCP tool routing
  144. --mcp-http-address A HTTP bind address (default: 127.0.0.1)
  145. --mcp-http-port N HTTP port for MCP server (default: 7777)
  146. --turbolink-join N Join local TurboLink shared session 1-255
  147. --headless Run without GUI (requires MCP or TurboLink)
  148. --portable Store configuration and user data beside the application
  149. -v, --version Display version information
  150. -h, --help Display this help message
  151. ```
  152. ### MCP Server
  153. Geargrafx includes a [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that enables AI-assisted debugging through AI agents like Claude Code, Codex and similar. The server provides tools for execution control, memory inspection, breakpoints, disassembly, hardware status, rewind and more. STDIO and HTTP transports are supported, with STDIO preferred.
  154. For complete setup instructions and tool documentation, see [MCP_README.md](MCP_README.md).
  155. ### TurboLink Multiplayer
  156. Choose the same session number in the `TurboLink` menu on both instances and select `Connect`, or start each process with `--turbolink-join N`. Sessions use local shared memory and support exactly two peers on one computer. Independent instances should use separate application copies or `--portable` data directories so configuration, saves, and single-instance handling do not conflict.
  157. ### Agent Skills
  158. Geargrafx provides [Agent Skills](https://agentskills.io/) that teach AI assistants how to effectively use the emulator for specific tasks:
  159. - **[geargrafx-debugging](skills/geargrafx-debugging/SKILL.md)** — Game debugging, code tracing, breakpoint management, hardware inspection, and reverse engineering.
  160. - **[geargrafx-romhacking](skills/geargrafx-romhacking/SKILL.md)** — Cheat creation, memory searching, ROM data modification, text translation, and game patching.
  161. Install with `npx skills add drhelius/geargrafx`. See the [skills README](skills/README.md) for details.
  162. ## Build Instructions
  163. ### Windows
  164. - Install Microsoft Visual Studio Community 2026 or later.
  165. - Download the latest SDL3 VC development libraries from [SDL3 Releases](https://github.com/libsdl-org/SDL/releases) (the file named `SDL3-devel-x.y.z-VC.zip`).
  166. - Extract the archive and rename the resulting folder (e.g. `SDL3-x.y.z`) to `SDL3`.
  167. - Place the `SDL3` folder inside `platforms/windows/dependencies/` so that the include path is `platforms/windows/dependencies/SDL3/include/SDL3/`.
  168. - Open the Geargrafx Visual Studio solution `platforms/windows/Geargrafx.sln` and build.
  169. ### macOS
  170. - Install Xcode and run `xcode-select --install` in the terminal for the compiler to be available on the command line.
  171. - Run these commands to generate a Mac *app* bundle:
  172. ``` shell
  173. brew install sdl3
  174. cd platforms/macos
  175. make dist
  176. ```
  177. ### Linux
  178. - Ubuntu / Debian / Raspberry Pi (Raspbian):
  179. If you are using Ubuntu 26.04, you can install SDL3 directly. Use the following commands to build:
  180. ``` shell
  181. sudo apt install build-essential pkg-config libsdl3-dev libgl-dev
  182. cd platforms/linux
  183. make
  184. ```
  185. For Ubuntu 24.04, you need to build SDL3 from source first. Use the following commands to build both SDL3 and Geargrafx:
  186. ``` shell
  187. sudo apt install build-essential cmake git curl jq pkg-config \
  188. libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev \
  189. libxi-dev libxss-dev libxkbcommon-dev libwayland-dev libdecor-0-dev \
  190. libdrm-dev libgbm-dev libgl1-mesa-dev libegl1-mesa-dev libdbus-1-dev libudev-dev libxtst-dev
  191. SDL3_TAG=$(curl -s https://api.github.com/repos/libsdl-org/SDL/releases/latest | jq -r '.tag_name')
  192. git clone --depth 1 --branch "$SDL3_TAG" https://github.com/libsdl-org/SDL.git /tmp/SDL3
  193. cmake -S /tmp/SDL3 -B /tmp/SDL3/build -DCMAKE_INSTALL_PREFIX=/usr -DSDL_TESTS=OFF -DSDL_EXAMPLES=OFF
  194. cmake --build /tmp/SDL3/build -j$(nproc)
  195. sudo cmake --install /tmp/SDL3/build
  196. cd platforms/linux
  197. make
  198. ```
  199. - Fedora:
  200. ``` shell
  201. sudo dnf install @development-tools gcc-c++ SDL3-devel
  202. cd platforms/linux
  203. make
  204. ```
  205. - Arch Linux:
  206. ``` shell
  207. sudo pacman -S base-devel sdl3
  208. cd platforms/linux
  209. make
  210. ```
  211. ### BSD
  212. - FreeBSD:
  213. ``` shell
  214. su root -c "pkg install -y git gmake pkgconf sdl3"
  215. cd platforms/bsd
  216. USE_CLANG=1 gmake
  217. ```
  218. - NetBSD:
  219. ``` shell
  220. su root -c "pkgin install gmake pkgconf SDL3"
  221. cd platforms/bsd
  222. gmake
  223. ```
  224. - OpenBSD
  225. ``` shell
  226. doas pkg_add gmake sdl3
  227. cd platforms/bsd
  228. LDFLAGS=-L/usr/X11R6/lib/ USE_CLANG=1 gmake
  229. ```
  230. ### Libretro
  231. - Ubuntu / Debian / Raspberry Pi (Raspbian):
  232. ``` shell
  233. sudo apt install build-essential
  234. cd platforms/libretro
  235. make
  236. ```
  237. - Fedora:
  238. ``` shell
  239. sudo dnf install @development-tools gcc-c++
  240. cd platforms/libretro
  241. make
  242. ```
  243. ## Contributors
  244. Thank you to all the people who have already contributed to Geargrafx!
  245. [![Contributors](https://contrib.rocks/image?repo=drhelius/geargrafx)](https://github.com/drhelius/geargrafx/graphs/contributors)
  246. ## License
  247. Geargrafx is licensed under the GNU General Public License v3.0 License, see [LICENSE](LICENSE) for more information.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.