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 a game with the Live Editor enabled by default, select and inspect on-screen controls, preview layout changes before writing guarded .rpy source, drive runtime 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, Live Editor, CLI, dashboard) are functional; APIs may still change.

Live Editor — select an editable control, inspect it, preview moves, then Save to source

Dashboard — live control of a running game	Live Editor — locked targets stay inspectable with a clear reason
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.) Launch the game and click the floating RF control to open the Live Editor.

Live Editor

The Live Editor is the headline 0.7 feature: edit eligible on-screen controls inside the running game, preview layout changes at runtime, and Save only when a target is source-safe. Locked or unsupported targets stay inspectable with a clear reason — they are not silently forced.

Audience	Start here
Human	Dashboard or game window → launch → click RF → select from canvas or scene tree → inspect / move where editable → Save → stop cleanly.
AI agent	renforge_info (read live_editor) → renforge_launch → poll renforge_launch_status → renforge_screenshot / renforge_scene_tree → guarded renforge_click_at or renforge_click_element → verify → renforge_stop.

Full human and agent workflows, source-safety rules, and screenshots: docs/LIVE_EDITOR.md.

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

• Live Editor (default on launch) — in-game selection, inspection, and source-safe preview/Save for editable controls; locked targets stay inspectable. Guide: docs/LIVE_EDITOR.md.
• Project inspection — summarize structure, scan scripts/labels/assets, parse lint output.
• Live game control — launch a project with an injected in-game bridge and Live Editor, 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.
• Scene perception (pixel-perfect, no vision needed) — read the whole frame as structured logical-coordinate nodes (renforge_scene_tree): every sprite, control, and text block with bounds, z-order, colour, and style, plus an ASCII wireframe and structural scene diffs. Then renforge_measure reports alignment, spacing, overlap, fit, and WCAG contrast as numbers an agent can act on.
• Autopilot — auto-play choices backed by Ren'Py menu items across fresh replays, including custom-named and one-item menus, while reporting label coverage and crashes. Custom call_screen interactions that do not expose Ren'Py menu items are not currently explored automatically.
• 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

• Live Editor — human and agent workflows, editable vs locked targets, source-safety, public screenshots.
• MCP guide — full tool catalogue, agent workflows (Live Editor, hot reload, saves, pixel-perfect placement, scene perception).
• Runtime policy — operation-level risk enforcement vs MCP ToolAnnotations, authorization, and the compatibility plan.
• Architecture — code layout, live-control flow, Ren'Py SDK resolution, packaging.
• Contributing — dev setup, frontend build, PRs.
• Cloud / CI environment — Cursor Cloud Agents, Xvfb, Ren'Py SDK bootstrap, and env smoke.
• Changelog — release history.
• examples/demo_game/ — small sample Ren'Py project to try everything on.

License

MIT

Contributors

Special thanks to the people who have contributed to RenForge:

• @AxelBeary — complete Simplified Chinese dashboard translation and related internationalization fixes.