renforge

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

Installed with	How to update
uvx … @latest	Nothing to do — @latest fetches the newest release on each start
pipx (full or slim)	pipx upgrade renforge
pip / venv	pip install -U "renforge[ui]" (or renforge for slim)

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"]
    }
  }
}

Client	Config file
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	cline_mcp_settings.json
Gemini CLI	~/.gemini/settings.json

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