Watch

Watch automatically re-runs selected checks after relevant file changes during an active editing session.

What Watch does

Watch re-runs a selected BranchPy check after you save a file � no manual re-run needed during an editing session.

Watch is a re-run trigger, not a live analysis engine. It does not keep the full BranchPy model continuously updated. Each save triggers a single, bounded run of the configured command and then waits for the next change.

What is monitored

Config changes (.branchpy.toml) are always watched so that settings adjustments trigger a fresh run immediately.

How to start

branchpy watch --project <path>

This starts Watch with the default command (checks). Press Ctrl+C to stop.

Specifying the command to re-run

branchpy watch --project <path> --cmd stats

Available commands: checks (default), stats, tests, media-missing, doctor.

Note: Watch supports lightweight commands only. Commands that require full project analysis � such as analyze, compare, and flowchart � are not supported in Watch mode. Run those on demand or in CI.

Adjusting the debounce delay

branchpy watch --project <path> --debounce 500

The default is 300 ms. Increase this on large projects if you see multiple back-to-back runs triggered by a single save.

VS Code integration

branchpy watch --project <path> --emit-notify

--emit-notify makes Watch emit events after each run so VS Code can surface results in the Problems panel and Control Center without you switching windows.

In VS Code the Control Center Watch feature always re-runs Analyze and Stats when files change. Compare is not watched � it compares saved results and must be refreshed manually after new analyses are generated.

Example output

[BranchPy Watch] Monitoring project: C:\projects\mygame
[BranchPy Watch] Command: checks
[BranchPy Watch] Debounce: 300ms
[BranchPy Watch] Press Ctrl+C to stop

[BranchPy Watch] File changed: game/script.rpy
... checks output ...
[BranchPy Watch] Command completed with exit code: 0

When to use Watch

Watch is for active editing sessions � start it when you sit down to write, stop it when you are done. It is not designed for background operation. Leaving it running indefinitely accumulates CPU (polling every 500 ms), keeps file paths in memory until stopped, and risks triggering long runs during idle periods.

CPU � The watcher polls every 500 ms regardless of whether files changed. This is lightweight on small-to-medium projects but adds up during long idle periods.

Memory � Watch holds the path and last-modified timestamp of every monitored file in memory. For a large project (thousands of .rpy files and assets), this is typically 0.5�2 MB � not significant on its own, but it is not released until you stop Watch.

Terminal � Watch runs in the foreground. Keep a dedicated terminal window for it so your main terminal stays free.

Command timeout � Each triggered run is killed after 5 minutes if it has not finished. If your project routinely takes longer to analyze, prefer running the command manually.

Recommendation: Start Watch when you sit down to edit, stop it when you are done. Avoid running it overnight or in CI � use scheduled or trigger-based CI runs instead.

Tips

• Use --cmd doctor to get health-check feedback on every save while setting up a new project.
• Use --cmd media-missing during asset work to see immediately if a newly added character sprite is referenced but not yet on disk.
• Combine with --emit-notify in VS Code to keep the Problems panel updated without switching windows.
• On large projects (thousands of .rpy files), use --cmd checks or --cmd doctor � these are the lightest options.

Learn more: CLI Reference