The Process: Begin, Create Files, Execute

Let’s walk through a complete batch operation workflow with a real-world example: creating a complete player controller system with 10 scripts.

Step-by-step process:

1. Begin batch mode
   unity.batch_operation action="begin"
   Response: “Recompilation frozen. You can now create multiple files.”
   
   At this point, Unity’s AssetDatabase stops watching for file changes. The file system watcher is paused. You can create as many files as you want without triggering recompilation.
2. Create files
   Vex creates all the scripts needed for the player controller system:
   
   file.create path="Assets/Scripts/Player/PlayerController.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerMovement.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerInput.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerHealth.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerInventory.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerAnimator.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerCamera.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerAudio.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerUI.cs" content="..." dry_run=false
file.create path="Assets/Scripts/Player/PlayerStats.cs" content="..." dry_run=false
   
   Each file.create completes instantly. No waiting. No recompilation. Just rapid file creation.
3. Execute batch
   unity.batch_operation action="execute"
   Response: “Recompilation unfrozen. Triggering recompile for 10 files.”
   
   Unity’s AssetDatabase resumes watching for changes, detects all 10 new files, and starts one recompilation cycle.
4. Wait for recompilation
   Unity recompiles once (5-15 seconds depending on project size)
   
   During this time, Unity processes all 10 files together. The compiler sees all the scripts at once, which can actually be faster than compiling them individually because it can optimize dependencies.
5. Continue work
   All scripts are compiled and ready to use
   
   Vex can now reference these scripts in subsequent commands (e.g., adding PlayerController component to a GameObject).

Time comparison:

• Without batch mode: 10 files × 10 seconds per recompile = 100 seconds
• With batch mode: 1 recompile = 10 seconds
• Time saved: 90 seconds (9x faster)

Automatic detection:

The workspace.plan system automatically detects when a plan has multiple recompile-triggering tasks and recommends batch mode to Vex. For example, if a plan includes:

• Phase 1: Create player scripts (10 tasks)
• Phase 2: Create enemy scripts (15 tasks)
• Phase 3: Create UI scripts (8 tasks)

Vex will use batch mode for each phase, resulting in 3 recompiles instead of 33. Total time saved: 150-450 seconds.

Safety:

If something goes wrong during batch mode (Unity crashes, error in a script, etc.), you can abort:

unity.batch_operation action="abort"

This unfreezes recompilation without triggering it. The files you created remain, but Unity doesn’t try to compile them. You can then fix any issues and manually trigger recompilation when ready.

Best practices:

• Use batch mode for 5+ files to see meaningful time savings
• Don’t leave batch mode active indefinitely—execute or abort within a few minutes
• If you’re unsure whether batch mode is active, call unity.batch_operation action="status"