Skip to main content
Lab Grimoire
TW EN
☕ Coffee
Spellbook / RPG-Harness: A Headless RPG Engine Built for AI Agents
ai-tools

RPG-Harness: A Headless RPG Engine Built for AI Agents

RPG-Harness turns game creation and playtesting into pure CLI commands that AI agents can drive natively. Brilliant headless design, but pre-alpha maturity means only adventurous developers should touch it right now.

Best For

Developers who want AI agents (especially Claude Code) to create, test, or play RPG/visual-novel content without a GUI. If you are exploring gamified education or interactive storytelling driven entirely by an LLM, this is the only engine designed headless-first for that exact workflow.

How I Actually Use It

I evaluated RPG-Harness as a potential building block for gamified biotech teaching modules. The core loop is straightforward: a game is just a folder of Markdown and YAML files. You run rpgh step, pipe in a JSON decision, and get back the updated game state as JSON. No window, no renderer, no SDK dependency.

The project ships two Claude Code skills out of the box: rpg-harness-player (for playing a game) and rpg-harness-author (for writing new game content). Drop the SKILL.md files into your Claude Code environment and the AI immediately knows how to interact with any game folder.

I tested the flagship demo game ("Youtou Kitan"), which showcases 15 lifecycle hooks, a full Condition AST, and composite triggers. The architecture is solid and extensible.

Where It Is Strong

  • Headless step API is pure-function perfection. JSON in, JSON out, no hidden state, fully scriptable. This is exactly how AI-native tooling should work.
  • Game = folder. No package.json, no node_modules. Content creators never touch the Node ecosystem.
  • Built-in Claude Code skills. The player and author protocols are ready to install, making AI integration zero-config.
  • Three game modes from one engine. Pure visual novel, training, and extraction-shooter variants all run on the same state machine, with room to extend.

Where It Fails

  • Pre-alpha, 1 commit, 0 releases. The API is not frozen. Expect breaking changes.
  • Bun runtime required. Not universally installed; adds friction to environments standardized on Node or pnpm.
  • Combat, training modules, and web frontend are incomplete. The rpgh studio command is labeled "PR-stage" (not yet functional).
  • Tiny community. 17 stars on GitHub at the time of review. If the author abandons it, there is no ecosystem to fall back on.

Pricing, Difficulty, and Risk

Price: Free, MIT-licensed. No commercial restrictions.

Difficulty: Advanced. You need comfort with TypeScript monorepos, Bun as a runtime, and CLI-driven game design. There is no GUI fallback.

Risk: High instability risk due to pre-alpha status. The API surface will almost certainly change. Data risk is negligible since everything runs locally with no cloud dependency. Supply chain is auditable (Bun + TypeScript, no opaque binaries).

Verdict

RPG-Harness nails the design philosophy: a headless, pure-function game engine that treats AI as a first-class player and author. If you need a production-ready tool today, look elsewhere. If you want to watch an architecturally elegant project mature and potentially become the standard way AI agents interact with game worlds, bookmark it and revisit when it ships its first tagged release.

Source