BranchPy — Analyze, Understand, and Fix Your Ren'Py Project
Stop guessing what's happening in your visual novel.
BranchPy gives you a complete, structured view of your project — flowcharts, errors, assets, and story statistics — directly inside VS Code.
Visualize your entire story structure as an interactive, navigable graph
Why BranchPy?
Most Ren'Py projects grow into spaghetti branching, hidden dead paths, missing assets, and logic bugs that are hard to trace.
BranchPy turns that into clear structure, actionable diagnostics, and fast iteration.
Quick Start (2–3 minutes)
1. Install the CLI
pip install branchpy-cli
2. Install this extension
From the VS Code Marketplace (you are here)
3. Open your Ren'Py project
Launch BranchPy from the sidebar, run Analyze, and explore your results.
After install, the CLI is available as:
branchpy
Verify with:
branchpy --help
Prefer a one-click install?
Download the Windows installer (no Python setup required):
https://branchpy.com/download/
What you can do
Detect issues instantly
Find unreachable labels, dead ends, and logic issues — with exact file and line references
Understand your variables across every story path
See how every variable behaves across all execution paths — spot instability and dead assignments
Find missing and unused assets
Three-tier asset review: cleanup candidates, needs review, and dynamic-load risk — safe to act on immediately
Jump straight to the source
Click any issue or variable — jump directly to the relevant line in your .rpy file
Requirements
- VS Code 1.90.0 or later
- Python 3.11+
- BranchPy CLI installed via
pip install branchpy-cli
Example CLI commands
branchpy analyze --project .
branchpy flowchart --project . --html --open
branchpy media --project .
branchpy stats --project .
Key features
Story Flow Visualization (FlowchartPlus)
Transform your project into an interactive flowchart directly inside VS Code.
- Live flowchart — edit a
.rpy file, watch the chart update automatically
- Layout selector — Narrative (ELK), Breadth-first, Force-directed, Grid, and Circle
- Narrative Signals — SCR (scene complexity) and RBI (reader branching index) badges
- Stale banner — one-click Refresh when the chart is out of date
- SVG export —
Ctrl+Shift+S when the panel is focused
- Reproduce in Terminal — copy the exact CLI command for any analysis run
Analysis & Reporting
- Run analysis from the Control Center or Command Palette
- Results open immediately with a loading state — no blank panels
- Real-time status bar: issue count and current tier (
BranchPy: Free|Pro|Team)
- Compare any two reports interactively
- Reports auto-organised by project with 50-file rotation
- Image Validation V3 — live-pipeline deduplication and canonical adoption
- Three review tiers: cleanup candidates / needs review / dynamic-load risk
- Confidence score per file (0–100) showing which signals triggered
- Protected-path detection for
gui/, renpy/, fonts/, etc.
- Bulk-delete gated to cleanup candidates only — safe by default
Semantics & Project Functions
- Project Function Index (PFI) — all functions, usages, and stat impacts
- Variable Explorer — dedicated sidebar view for variable inspection
- Omega PF Triads — sidebar view for Omega PF classification scatter
Custom Rules & Governance
- Display custom rule violations in the Problems panel with quick fixes
- Validate
rules_custom.yml on save
- Governance panel with rule batching and policy management
Diagnostics & Logging
- Doctor — environment diagnostics: Python, CLI, dependencies
- Error/Usage Console — real-time command logs with filtering
- History Panel — structured action log with CSV/JSON export
- Log streaming — live tail of BranchPy operations
License Management
- Activate a license key:
Ctrl+Shift+P → "BranchPy: Activate License"
- Status bar shows current tier; click to view or upgrade
- Full deactivation or keep-key mode for seat transfers
Trust & Transparency
- Local-first — your project files stay on your machine
- No data upload by default — telemetry is opt-in and anonymous
- AI features are optional — explicit consent required on first enable; off by default
Commands
| Command |
Action |
bpy.reports.analyze |
Run analysis on the current project |
bpy.showReportPanel |
Open the report panel |
bpy.reports.compare |
Compare any two reports interactively |
bpy.reports.stats |
Project statistics and metrics |
branchpy.export.flowchart |
Open flowchart (Ctrl+Shift+E in panel) |
branchpy.export.svg |
Export flowchart as SVG (Ctrl+Shift+S) |
branchpy.imageValidation |
Open Image Validation panel |
bpy.mediaMissing |
List missing media assets |
bpy.mediaUnused |
List unreferenced media assets |
bpy.doctor |
Run environment diagnostics |
bpy.console.open |
Open Control Center |
bpy.showHistoryPanel |
Open action history |
bpy.showNotifications |
Open notifications panel |
bpy.activateLicense |
Activate a Pro or Team license key |
bpy.deactivateLicense |
Deactivate (full removal or keep-key) |
Configuration
| Setting |
Default |
Description |
branchpy.cliLaunch |
pythonModule |
Launch as Python module or CLI executable |
branchpy.cliPath |
— |
Path to CLI executable (if not using Python module) |
branchpy.ai.enabled |
false |
Enable AI features (consent dialog on first enable) |
branchpy.captureCli |
false |
Enable CLI event capture for live notifications |
branchpy.notifications.maxItems |
500 |
Maximum notifications to retain |
branchpy.notifications.showBadge |
true |
Show unread count badge |
Documentation
Full documentation: https://branchpy.com/docs/1.1.1/
Licensing
BranchPy follows a dual-license model:
- Free (Non-Commercial) — all features, attribution required
- Pro / Team (Commercial) — all features, no attribution required, priority support
Am I commercial? If you sell your game, run ads, accept paid subscriptions, do client work, or work in a studio → Commercial.
What's new in 1.1.19
- Extension icon added — visible in VS Code search, Extensions panel, and Marketplace
- Screenshots added to Marketplace listing
- Marketplace listing overhauled: verified commands, accurate requirements, live links
