Git Worktree Overview

Git Worktree is a core feature in MoAI-ADK for parallel development. It provides complete isolation by allowing each SPEC to be developed in an independent environment.

Why Do We Need Worktree?

Problem: Shared LLM Settings

In traditional MoAI-ADK, when you use moai glm or moai cc to change the LLM, the same LLM is applied to all open sessions. This causes the following issues:

• SPEC Interference: LLM settings affect each other when developing different SPECs
• No Parallel Development: Cannot develop multiple SPECs simultaneously
• Cost Inefficiency: Must use expensive Opus in all sessions

Solution: Complete Isolation

With Git Worktree, each SPEC maintains completely independent Git state and LLM settings:

Core Workflow

3-Step Development Process

MoAI-ADK development with Git Worktree consists of 3 steps:

Step-by-Step Details

Step 1: Plan (Terminal 1)

Generate a SPEC document using Claude 4.5 Opus:

> /moai plan "Add authentication system" --worktree

What happens:

• Automatic creation of SPEC document in EARS format
• Automatic creation of Worktree for that SPEC
• Automatic creation and checkout of feature branch

Results:

• .moai/specs/SPEC-AUTH-001/spec.md
• New Worktree directory
• feature/SPEC-AUTH-001 branch

Step 2: Implement (Terminals 2, 3, 4…)

Implement using GLM 5 or other cost-effective models:

# Enter Worktree (new terminal)
$ moai worktree go SPEC-AUTH-001
 
# Change LLM
$ moai glm
 
# Start development
$ claude
> /moai run SPEC-AUTH-001
> /moai sync SPEC-AUTH-001

Benefits:

• Completely isolated working environment
• GLM cost efficiency (70% savings vs Opus)
• Unlimited parallel development without conflicts

Step 3: Merge & Cleanup

moai worktree done SPEC-AUTH-001              # main → merge → cleanup
moai worktree done SPEC-AUTH-001 --push       # above + push to remote

Worktree Command Reference

Key Benefits of Worktree

1. Complete Isolation

Each SPEC maintains independent Git state:

Benefits:

• Can commit independently in each Worktree
• Work without branch conflicts
• Only completed SPECs are merged to main

2. LLM Independence

Each Worktree maintains separate LLM settings:

3. Unlimited Parallel Development

Can develop multiple SPECs simultaneously:

# Terminal 1: Plan SPEC-AUTH-001
> /moai plan "authentication system" --worktree
 
# Terminal 2: Implement SPEC-AUTH-002 (GLM)
$ moai worktree go SPEC-AUTH-002
$ moai glm
> /moai run SPEC-AUTH-002
 
# Terminal 3: Implement SPEC-AUTH-003 (GLM)
$ moai worktree go SPEC-AUTH-003
$ moai glm
> /moai run SPEC-AUTH-003
 
# Terminal 4: Document SPEC-AUTH-004
$ moai worktree go SPEC-AUTH-004
> /moai sync SPEC-AUTH-004

4. Safe Merge

Only completed SPECs are merged to main branch:

Parallel Development Visualization

Working simultaneously in multiple terminals:

Next Steps

• Complete Guide - All Git Worktree commands and detailed usage
• Real Examples - Real-world usage examples
• FAQ - Frequently asked questions and troubleshooting

Related Documents

• MoAI-ADK Documentation 
• SPEC System
• DDD Workflow