Worktree Management
Relevant source files
The following files were used as context for generating this wiki page:
Worktree Management in the ECC project provides a robust mechanism for parallelizing development tasks by utilizing Git worktrees to isolate state. This system is primarily employed when the project requires multi-model collaboration or parallel execution of tasks that need independent Git environments, separate build processes, or isolated testing execution.
The orchestration of these worktrees allows the system to split work across multiple workers without cross-contamination of Git state. This is critical for complex multi-model workflows where different AI agents (e.g., Codex for backend, Gemini for frontend) might otherwise conflict if working within a single shared directory.
Sources: commands/multi-workflow.md:143-150, AGENTS.md:164-170
Architecture and Orchestration
The management of worktrees is handled through a combination of Node.js scripts and specialized agents. The orchestrate-worktrees.js script serves as the primary entry point for executing complex plans across isolated environments.
Orchestration Flow
When a multi-model workflow requires parallel workers, the orchestrator provisions these workers by creating distinct Git worktrees based on a JSON implementation plan. Each worker operates within its own terminal and maintains its own Git state.
The diagram above illustrates how the Orchestrator splits a centralized plan into isolated execution environments using Git worktrees.
Sources: commands/multi-workflow.md:143-150, scripts/orchestrate-worktrees.js
Components and Logic
The worktree system is implemented across multiple layers of the project, including JavaScript lifecycle scripts and Rust-based core modules.
Worktree Lifecycle Management
The lifecycle management involves initializing, tracking, and cleaning up worktrees used during the development process. This is supported by a dedicated module in ecc2/src/worktree/mod.rs and JavaScript utilities in scripts/lib/worktree-lifecycle/git.js.
| Component | Responsibility | File Reference |
|---|---|---|
worktree-lifecycle.js | Main entry for managing the birth-to-death cycle of a worktree | scripts/worktree-lifecycle.js |
mod.rs | Rust implementation for low-level worktree operations | ecc2/src/worktree/mod.rs |
git.js (Lifecycle) | Git-specific wrapper commands for worktree creation and removal | scripts/lib/worktree-lifecycle/git.js |
orchestrate-worktrees.js | High-level execution of JSON-defined plans across worktrees | scripts/orchestrate-worktrees.js |
Sources: ecc2/src/worktree/mod.rs, scripts/worktree-lifecycle.js, scripts/lib/worktree-lifecycle/git.js
Core Logic for Parallel Workers
The multi-workflow command explicitly triggers worktree orchestration when the "LITE_MODE" is insufficient for the complexity of the task. If a task requires isolated build/test execution, the system calls:
node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
This ensures that the "Orchestrator" (Claude) can manage sub-agents like Codex and Gemini while they perform heavy lifting in separate directory paths.
Sources: commands/multi-workflow.md:143-150, AGENTS.md:164-170
Integration with AI Agents
Worktree management is a key differentiator in how the Orchestrator agent interacts with specialized sub-agents. While in-process sub-agents are used for lightweight analysis, worktrees are mandated for:
- Parallel operations requiring independent terminals.
- Isolated Git states (preventing merge conflicts during simultaneous implementation).
- Independent build/test execution cycles.
Multi-Model Execution Sequence
The following sequence shows how the system handles a multi-model task using worktrees:
The sequence demonstrates the separation of concerns where each AI model is granted a dedicated worktree to prevent filesystem contention.
Sources: commands/multi-workflow.md:143-150, AGENTS.md:164-170
Summary
Worktree Management within ECC is an advanced orchestration layer designed to handle the complexities of multi-model AI development. By leveraging Git's native worktree capabilities, the project allows for truly parallel, isolated, and safe execution of backend and frontend tasks. This system ensures that code generation, testing, and building can occur simultaneously across different sub-agents without compromising the integrity of the main Git branch or local environment.