How Video-Use Spawns Parallel Sub-Agents for Multiple Animation Slots

Video-Use spawns parallel sub-agents by invoking the Agent tool simultaneously for each animation slot, creating isolated briefs that allow concurrent rendering while preventing file conflicts.

The video-use repository orchestrates complex video editing workflows by distributing animation rendering across multiple isolated agents. When processing video overlays, the system creates distinct animation slots and spawns parallel sub-agents to handle each render independently. This architecture reduces total wall-time to the duration of the slowest animation rather than the sum of all individual renders.

Architecture of Animation Slots

The foundation of parallel processing lies in the slot directory structure defined in SKILL.md.

Slot Directory Isolation

Each animation receives a dedicated workspace under edit/animations/slot_<id>/. According to the directory layout specified at [line 49 of SKILL.md](https://github.com/browser-use/video-use/blob/main/SKILL.md#L49), these folders hold source files, scripts, and the final render for individual animations. This isolation ensures that concurrent sub-agents never encounter file system conflicts.

Self-Contained Brief Generation

For every slot, the system constructs a self-contained brief containing the goal, output path, technical specifications, palette, timeline, and anti-list. As documented in [SKILL.md lines 49-60](https://github.com/browser-use/video-use/blob/main/SKILL.md#L49), these briefs are deliberately independent—the sub-agent receives no parent context, enabling true parallel execution without coordination overhead.

Spawning Parallel Sub-Agents with the Agent Tool

The parallelization mechanism relies on the generic Agent tool invoked in a non-blocking manner.

Parallel Invocation Pattern

The main process spawns all sub-agents simultaneously. As specified at [line 31 of SKILL.md](https://github.com/browser-use/video-use/blob/main/SKILL.md#L31), the rule is to "Spawn N at once via the Agent tool" rather than sequentially. This approach ensures that the total processing time equals the duration of the slowest animation, not the cumulative sum.

Isolated Execution Guarantees

Each sub-agent operates within its own sandbox, rendering overlays using HyperFrames, Remotion, Manim, or PIL. The system enforces a strict "one sub-agent = one file" rule documented at [line 62 of SKILL.md](https://github.com/browser-use/video-use/blob/main/SKILL.md#L62), preventing overwrites and ensuring deterministic output. After rendering, each agent verifies duration via ffprobe and writes the final file (render.mp4 or render.webm) into its respective slot directory, as detailed in [SKILL.md lines 100-113](https://github.com/browser-use/video-use/blob/main/SKILL.md#L100).

Implementation: Creating Slots and Launching Agents

The following example demonstrates how to programmatically create isolated slots and spawn parallel sub-agents. This pattern illustrates the architecture described in the repository documentation:

# helpers/launch_animations.py

import os, json, subprocess, uuid
from pathlib import Path

def create_slot(base_dir: Path) -> Path:
    """Create a unique slot directory under <edit>/animations/."""
    slot_id = uuid.uuid4().hex[:8]
    slot_dir = base_dir / f"slot_{slot_id}"
    slot_dir.mkdir(parents=True, exist_ok=True)
    return slot_dir

def build_brief(slot_dir: Path, spec: dict) -> str:
    """Write a self‑contained brief JSON file for the sub‑agent."""
    brief = {
        "goal": f"Build ONE animation: {spec['description']}",
        "output_path": str(slot_dir / "render.mp4"),
        "technical": spec["technical"],
        "palette": spec["palette"],
        "timeline": spec["timeline"],
        "anti_list": ["no chrome", "no extra titles"],
        "deliverable_checklist": ["script", "render", "ffprobe verification"]
    }
    brief_path = slot_dir / "brief.json"
    brief_path.write_text(json.dumps(brief, indent=2))
    return str(brief_path)

def spawn_sub_agent(brief_path: str):
    """Launch the sub‑agent in parallel (non‑blocking)."""
    # The actual Agent CLI could be `claude-agent`, `openai-agent`, etc.

    subprocess.Popen(["agent", "run", "--brief", brief_path])

def launch_all_animations(edit_dir: Path, animation_specs: list):
    """Create slots and start all agents in parallel."""
    slots = []
    for spec in animation_specs:
        slot_dir = create_slot(edit_dir / "animations")
        brief_path = build_brief(slot_dir, spec)
        spawn_sub_agent(brief_path)
        slots.append(slot_dir)
    return slots

This implementation creates unique slot directories, writes isolated briefs, and uses subprocess.Popen to launch agents without awaiting completion, achieving true parallelism.

Consolidation into Final Render

After all parallel sub-agents complete their renders, the main render.py process consolidates the outputs. According to [SKILL.md lines 82-86](https://github.com/browser-use/video-use/blob/main/SKILL.md#L82), the system reads the generated overlay files from each slot_<id> directory and populates the overlays array in the final EDL (Edit Decision List). The helpers/render.py script then assembles these isolated renders into the completed video sequence.

Summary

• Slot isolation creates unique directories under edit/animations/slot_<id>/ to prevent file conflicts between concurrent processes.
• Self-contained briefs provide complete context to each sub-agent without requiring parent process coordination.
• Parallel invocation via the Agent tool launches all N sub-agents simultaneously, minimizing wall-time to the slowest render duration.
• Non-blocking execution using subprocess.Popen or equivalent mechanisms enables concurrent processing without sequential bottlenecks.
• Automatic consolidation allows render.py to gather completed renders from slot directories and assemble the final video.

Frequently Asked Questions

How does Video-Use prevent sub-agents from overwriting each other's files?

The architecture enforces strict directory isolation. Each sub-agent writes exclusively to its assigned slot_<id> directory, and the system implements a "one sub-agent = one file" rule as documented in SKILL.md. Because briefs are isolated and agents receive no shared context, they cannot access or modify other slots' files.

What information is included in each animation brief?

Each brief contains a complete specification including the animation goal, output path (e.g., slot_<id>/render.mp4), technical parameters (resolution, codec, fps), color palette, timeline segments, anti-list (prohibited elements), and deliverable checklist. This self-contained approach eliminates dependencies between parallel agents.

Why does Video-Use spawn agents in parallel rather than sequentially?

Parallel spawning reduces total processing time from the sum of all animation durations to the duration of the slowest individual render. Since animations have no interdependencies, sequential processing would waste wall-time. The SKILL.md explicitly mandates spawning N agents at once via the Agent tool to maximize throughput.

How does the main process know when all parallel sub-agents have completed?

While the example code launches agents with subprocess.Popen without blocking, production implementations typically monitor slot directories for completion markers or utilize process handles to await termination. The render.py script only proceeds to consolidate overlays after verifying that all expected render.mp4 files exist in their respective slot directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}