RenForge

RenForge is an MCP (Model Context Protocol) server, CLI, and web dashboard
for working with Ren'Py visual-novel projects.

It lets an AI agent — or a human via the dashboard — inspect a project, launch
and drive a running game, read/write game state, capture screenshots, generate
translations, find orphaned assets, run builds, and search Ren'Py's docs.

Status: alpha, actively developed. The core surfaces (MCP tools, in-game
bridge, CLI, dashboard) are functional; APIs may still change.

Story map — click a node to warp the running game	Asset audit — orphans, missing files, undefined images

Quick start — dashboard

Requires Python 3.11+ and uv — nothing else.
You don't even need Ren'Py installed: RenForge reuses an SDK it finds on your
machine, or downloads one automatically on first launch.

uvx --from "renforge[ui]@latest" renforge ui

Then choose your game in the dashboard's project picker — no path to type. (Or
skip the picker with --project /path/to/your/game.)

Install

uvx needs no install at all. For a persistent renforge command on your
PATH, use pipx:

# Full install — MCP + CLI + web dashboard
pipx install "renforge[ui]"
renforge ui

# Slim install — MCP server + CLI only (no dashboard deps)
pipx install renforge
renforge serve

[ui] pulls in the optional dashboard stack (Starlette, uvicorn, watchfiles).
Skip it if you only need the MCP server or CLI.

On managed systems (Debian/Ubuntu), plain pip install is blocked by
PEP 668 — use uvx or pipx instead.

Update

What's new: CHANGELOG.md ·
GitHub releases.

Set up the MCP server (AI agents)

The server command is the same for every client:

uvx renforge@latest serve

Every RenForge tool takes a project_path argument, so the agent passes your
game's path on each call — copy the configs below as-is, no path substitution.

Claude Code

claude mcp add renforge -- uvx renforge@latest serve

Codex CLI

codex mcp add renforge -- uvx renforge@latest serve

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — same mcpServers
JSON shape in each client's config file:

{
  "mcpServers": {
    "renforge": {
      "command": "uvx",
      "args": ["renforge@latest", "serve"]
    }
  }
}

VS Code (Copilot), Zed, Windows PATH issues, and the pipx variant are covered
in the MCP guide.

Verify it works — ask the agent:

Inspect my Ren'Py project at /path/to/game

The agent should call renforge_inspect_project with that path and return a
JSON summary of the project (labels, scripts, assets, and related metadata).

What it does

• Project inspection — summarize structure, scan scripts/labels/assets,
  parse lint output.
• Live game control — launch a project with an injected in-game bridge, then
  advance dialogue, list/select choices, evaluate expressions, get/set store
  variables, send focused text/key/scroll input, poll pushed events, and capture
  frames the model can literally see.
• Autopilot — auto-play the game across branches and report label coverage
  and crashes.
• Assets & translations — find orphaned/missing image+audio assets, list
  languages, compute translation stats, generate/update game/tl/<lang>/ files,
  export dialogue as text.
• Builds — package desktop distributions and web builds.
• Docs — search and read Ren'Py's offline documentation.
• Web dashboard — live story map, activity log, autopilot coverage, lint
  view, and game-state controls (default 127.0.0.1:8765).

CLI

renforge --version
renforge inspect <project>      # lightweight project summary (JSON)
renforge serve [--project .]    # start the MCP server (stdio transport)
renforge ui [--project <project>] [--port 8765]  # start the web dashboard

Documentation

• MCP guide — full tool catalogue, agent workflows
  (hot reload, saves, pixel-perfect placement), safety guards, troubleshooting.
• Architecture — code layout, live-control flow,
  Ren'Py SDK resolution, packaging.
• Contributing — dev setup, frontend build, PRs.
• Changelog — release history.
• examples/demo_game/ — small sample Ren'Py project to try everything on.

License

MIT