Git worktree management for parallel SPEC development with isolated workspaces, automatic branch registration, and seamless MoAI-ADK integration. Use when setting up parallel development environments.
Git worktree management for parallel SPEC development with isolated workspaces, automatic branch registration, and seamless MoAI-ADK integration. Use when setting up parallel development environments.
when_to_use
Use for git worktree management: parallel SPEC development with isolated workspaces, automatic branch registration, branch isolation, and seamless MoAI-ADK integration for multiple concurrent SPECs.
Git worktree management system for parallel SPEC development with isolated workspaces, automatic registration, and seamless MoAI-ADK integration.
Core Philosophy: Each SPEC deserves its own isolated workspace to enable true parallel development without context switching overhead.
Quick Reference (30 seconds)
What is MoAI Worktree Management?
A specialized Git worktree system that creates isolated development environments for each SPEC, enabling parallel development without conflicts.
Key Features:
Isolated Workspaces: Each SPEC gets its own worktree with independent Git state
Automatic Registration: Worktree registry tracks all active workspaces
Parallel Development: Multiple SPECs can be developed simultaneously
Seamless Integration: Works with /moai plan, /moai run, /moai sync workflow
Smart Synchronization: Automatic sync with base branch when needed
Cleanup Automation: Automatic cleanup of merged worktrees
Quick Access:
CLI commands: Refer to Worktree Commands Module at modules/worktree-commands.md
Management patterns: Refer to Worktree Management Module at modules/worktree-management.md
Parallel workflow: Refer to Parallel Development Module at modules/parallel-development.md
Integration guide: Refer to Integration Patterns Module at modules/integration-patterns.md
Troubleshooting: Refer to Troubleshooting Module at modules/troubleshooting.md
Use Cases:
Multiple SPECs development in parallel
Isolated testing environments
Feature branch isolation
Code review workflows
Experimental feature development
Implementation Guide (5 minutes)
1. Core Architecture - Worktree Management System
Purpose: Create isolated Git worktrees for parallel SPEC development.
Key Components:
Worktree Registry - Central registry tracking all worktrees
Manager Layer - Core worktree operations including create, switch, remove, and sync
CLI Interface - User-friendly command interface
Models - Data structures for worktree metadata
Integration Layer - MoAI-ADK workflow integration
Registry Structure:
The registry file stores worktree metadata in JSON format. Each worktree entry contains an identifier, file path, branch name, creation timestamp, last sync time, status (active or merged), and base branch reference. The config section defines the worktree root directory, auto-sync preference, and cleanup behavior for merged branches.
File Structure:
The worktree system creates a dedicated directory structure in the user's global home directory. At the worktree root (~/.moai/worktrees/{ProjectName}/), you will find the central registry JSON file and individual directories for each SPEC. Each SPEC directory contains a .git file for worktree metadata and a complete copy of all project files.
Detailed Reference: Refer to Worktree Management Module at modules/worktree-management.md
2. CLI Commands - Complete Command Interface
Purpose: Provide intuitive CLI commands for worktree management.
Core Commands:
To create a new worktree for a SPEC, use the new command followed by the SPEC ID and description. To list all worktrees, use the list command. To switch to a specific worktree, use the switch command with the SPEC ID. To get the worktree path for shell integration, use the go command with eval. To sync a worktree with its base branch, use the sync command. To remove a worktree, use the remove command. To clean up merged worktrees, use the clean command. To show worktree status, use the status command. For configuration management, use the config command with get or set subcommands.
Command Categories:
Creation: The new command creates an isolated worktree
Navigation: The list, switch, and go commands enable browsing and navigating
Management: The sync, remove, and clean commands maintain worktrees
Status: The status command checks worktree state
Configuration: The config command manages settings
Shell Integration:
For switching to a worktree directory, two approaches work well. The switch command directly changes to the worktree directory. The go command outputs a cd command that can be evaluated by the shell, which is the recommended pattern for shell scripts and automation.
Detailed Reference: Refer to Worktree Commands Module at modules/worktree-commands.md
3. Parallel Development Workflow - Isolated SPEC Development
Purpose: Enable true parallel development without context switching.
Workflow Integration:
During the Plan Phase using /moai plan, the SPEC is created and the worktree new command sets up automatic worktree isolation.
During the Development Phase, the isolated worktree environment provides independent Git state with zero context switching overhead.
During the Sync Phase using /moai sync, the worktree sync command ensures clean integration with conflict resolution support.
During the Cleanup Phase, the worktree clean command provides automatic cleanup with registry maintenance.
Parallel Development Benefits:
Context Isolation: Each SPEC has its own Git state, files, and environment
Zero Switching Cost: Instant switching between worktrees
Independent Development: Work on multiple SPECs simultaneously
Safe Experimentation: Isolated environment for experimental features
Clean Integration: Automatic sync and conflict resolution
Example Workflow:
First, create a worktree for SPEC-001 with a description like "User Authentication" and switch to that directory. Then run /moai run SPEC-001 to develop in isolation. Next, navigate back to the main repository and create another worktree for SPEC-002 with description "Payment Integration". Switch to that worktree and run /moai run SPEC-002 for parallel development. When needed, switch between worktrees and continue development. Finally, sync both worktrees when ready for integration.
Detailed Reference: Refer to Parallel Development Module at modules/parallel-development.md
Purpose: Seamless integration with MoAI-ADK Plan-Run-Sync workflow.
Integration Points:
During Plan Phase Integration with /moai plan, after SPEC creation, create the worktree using the new command with the SPEC ID. The output provides guidance for switching to the worktree using either the switch command or the shell eval pattern with the go command.
During Development Phase with /moai run, worktree isolation provides a clean development environment with independent Git state preventing conflicts and automatic registry tracking.
During Sync Phase with /moai sync, before PR creation run the sync command for the SPEC. After PR merge, run the clean command with the merged-only flag to remove completed worktrees.
Auto-Detection Patterns:
The system detects worktree environments by checking for the registry file in the parent directory. When detected, the SPEC ID is extracted from the current directory name. The status command with sync-check option automatically identifies worktrees that need synchronization.
Configuration Integration:
The MoAI configuration supports worktree settings including auto_create for automatic worktree creation, auto_sync for automatic synchronization, cleanup_merged for automatic cleanup of merged branches, and worktree_root for specifying the worktree directory location with project name substitution.
Detailed Reference: Refer to Integration Patterns Module at modules/integration-patterns.md
5. --spawn — Launch a Teammate Session in a New tmux Window
Purpose: start a Claude or GLM session in a worktree without giving up the session you are in.
The launch commands (moai cc, moai glm, moai cg) normally replace the running shell, which is right for "work here now" but cannot express "keep going and start a teammate alongside me". --spawn re-issues the same command in a new tmux window instead, then returns so the caller keeps working.
Combined with -w <name>, one command opens a teammate in an isolated worktree:
moai cg -w feat-auth --spawn # GLM teammate in .claude/worktrees/feat-auth
moai cc -w feat-auth --spawn # Claude teammate, same worktree
moai glm -w feat-auth --spawn # all-GLM teammate
Behavior:
The new window is created detached, so focus stays in the caller's pane. The printed pane id (e.g. %7) is the handle for switching to it.
The spawned window starts at the project root, so a short -w <name> value resolves against .claude/worktrees/<name>/.
--spawn is consumed by MoAI and never reaches Claude Code. Tokens after the -- pass-through marker are left untouched.
Arguments are shell-quoted, so a worktree name containing spaces or shell metacharacters reaches the spawned process intact.
Requirements — each is refused with a clear error rather than a silent fallback, because falling back would replace the caller's session, the exact outcome --spawn exists to avoid:
Missing
Message
$TMUX (not inside a session)
tmux session required for --spawn
tmux binary
--spawn requires the tmux binary
moai binary in PATH
--spawn needs the moai binary in PATH
No settings are mutated before these checks run, so a refusal leaves the environment untouched. The spawned command performs its own backend setup inside the new window.
Platform note: tmux is POSIX-only, so --spawn is unavailable on Windows and reports the missing binary. Entering a worktree in place with -w works on every platform.
Detailed Reference: the launcher's spawn entry point — flag stripping, command reconstruction with shell quoting, and the tmux window invocation.
Advanced Implementation (10+ minutes)
Multi-Developer Worktree Coordination
Shared Worktree Registry:
Configure team worktree settings by setting the registry type to team mode and specifying a shared registry path accessible to all team members. For developer-specific worktrees within the shared environment, use the developer flag when creating worktrees to prefix entries with the developer name. The list command with all-developers flag shows worktrees from all team members, and the status command with team-overview provides a consolidated team view.
Advanced Synchronization Strategies
Selective Sync Patterns:
The sync command supports selective synchronization with include and exclude patterns to sync only specific directories or files. For conflict resolution, choose between auto-resolve for simple conflicts, interactive resolution for manual conflict handling, or abort to cancel the sync operation.
Worktree Templates and Presets
Custom Worktree Templates:
Create worktrees with specific setups using the template flag. A frontend template might include npm install and eslint setup with pre-commit hooks. A backend template might include virtual environment creation, activation, and dependency installation. Configure custom templates through the config command by setting template-specific setup commands.
Performance Optimization
Optimized Worktree Operations:
For faster worktree creation, use the shallow flag with a depth value for shallow clones. The background flag enables background synchronization. The parallel flag with all option enables parallel operations across all worktrees. Enable caching through configuration with cache enable and cache TTL settings for faster repeated operations.
Works Well With
Commands:
/moai plan - SPEC creation with automatic worktree setup
/moai run - Development in isolated worktree environment
/moai sync - Integration with automatic worktree sync
/moai feedback - Worktree workflow improvements
Skills:
moai-foundation-core - Parallel development patterns
Cobra - CLI command framework and formatted output
Quick Decision Guide
For new SPEC development, use the worktree isolation pattern with auto-setup. The primary approach is worktree isolation and the supporting pattern is integration with /moai plan.
For parallel development across multiple SPECs, use multiple worktrees with shell integration. The primary approach is maintaining multiple worktrees and the supporting pattern is fast switching between them.
For team coordination in shared environments, use shared registry with developer prefixes. The primary approach is the shared registry pattern and the supporting pattern is conflict resolution.
For code review workflows, use isolated review worktrees. The primary approach is worktree isolation for reviews and the supporting pattern is clean sync after review completion.
For experimental features, use temporary worktrees with auto-cleanup. The primary approach is creating temporary worktrees and the supporting pattern is safe experimentation with automatic removal.
Module Deep Dives:
Worktree Commands: Refer to modules/worktree-commands.md for complete CLI reference
Worktree Management: Refer to modules/worktree-management.md for core architecture
Parallel Development: Refer to modules/parallel-development.md for workflow patterns
Integration Patterns: Refer to modules/integration-patterns.md for MoAI-ADK integration
Troubleshooting: Refer to modules/troubleshooting.md for problem resolution
Full Examples: Refer to references/examples.md
External Resources: Refer to references/reference.md
Common Rationalizations
Rationalization
Reality
"Worktree isolation is overkill for this small change"
Small changes on main cause merge conflicts when parallel work is in progress. Worktrees prevent this.
"I will just work on the main branch, it is faster"
Working on main blocks other agents from writing. Worktrees enable parallelism.
"Read-only agents need worktree isolation too, for safety"
Read-only agents cannot write because their tools list omits Write/Edit (the spawn-time mode parameter is deprecated and ignored). Adding isolation wastes resources with no benefit.
"I can skip worktree cleanup, git handles it"
Stale worktree branches accumulate and confuse git worktree list. Always prune after use.
"Absolute paths in agent prompts are fine since the worktree has the same structure"
Absolute paths to the main repo bypass worktree isolation entirely. Use relative paths.
Red Flags
Implementation agent spawned without isolation: worktree in team mode
Read-only agent spawned with isolation: worktree (unnecessary overhead)
Agent prompt contains absolute path to the main project directory for write targets
Worktree not pruned after team session completes (stale branches remain)
cd /absolute/project/path in Bash commands inside worktree-isolated agent prompts
Verification
Implementation teammates use isolation: worktree (check agent spawn parameters)
Read-only teammates do NOT use isolation: worktree (verify the tools list omits Write/Edit)
Agent prompts reference write-target files by relative paths only
git worktree list shows no stale worktrees after session ends
Worktree CWD isolation verified on Claude Code >= 2.1.97 (check version)
Hook scripts (handle-worktree-create.sh, handle-worktree-remove.sh) are present and executable
