RenForge

<!-- mcp-name: io.github.alex-jordan547/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.

<img src=".github/screenshots/live-editor-editable-selection.png" alt="RenForge Live Editor — selected editable control with scene tree, handles, inspector, and style panel" /> <p align="center"><em>Live Editor — select an editable control, inspect it, preview moves, then Save to source</em></p> <table> <tr> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/live-dark.png" /> <img src=".github/screenshots/live.png" alt="RenForge dashboard — live control of a running game" /> </picture> </td> <td width="50%"> <img src=".github/screenshots/live-editor-locked-reason.png" alt="Live Editor — locked selection with a clear human-readable reason" /> </td> </tr> <tr> <td align="center"><em>Dashboard — live control of a running game</em></td> <td align="center"><em>Live Editor — locked targets stay inspectable with a clear reason</em></td> </tr> <tr> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/storymap-dark.png" /> <img src=".github/screenshots/storymap.png" alt="Story map — interactive graph of labels and transitions" /> </picture> </td> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/assets-dark.png" /> <img src=".github/screenshots/assets.png" alt="Assets — orphaned, missing and undefined asset audit" /> </picture> </td> </tr> <tr> <td align="center"><em>Story map — click a node to warp the running game</em></td> <td align="center"><em>Asset audit — orphans, missing files, undefined images</em></td> </tr> </table>

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 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

• 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).
• 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

Contributors

Special thanks to the people who have contributed to RenForge:

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