Git Worktree Overview

Info

Belongs to: Agentic Harness

Git Worktree is the foundation of MoAI-ADK parallel development. It gives every SPEC a fully independent workspace, so you can keep different Git states and different LLM configurations running at the same time.

Platform basics

Background on the platform layer is in Worktrees. This page is the MoAI-ADK account of it.

Looked at through the Agentic Harness — the quality-control one of the three core values — Worktree is the control device that splits each SPEC’s workspace completely apart. Agents working in parallel never overwrite each other’s work, and only completed SPECs get merged into main. A cost benefit (Tokenomics) follows from it: each worktree can be given its own LLM execution mode, so a high-reasoning Claude model can run in the planning terminal while a low-cost GLM runs in the implementation terminal — one model assigned per phase.

Without Worktree, switching the LLM backend with moai glm or moai cc applies the same configuration to every open session of the project. As a result:

• Cross-SPEC interference — an LLM change made for one SPEC shakes up work on other SPECs
• No parallel development — you cannot run multiple SPECs under different conditions at the same time
• Wasted tokens — even simple implementation work runs on the expensive model

With Git Worktree, each SPEC’s Git state and LLM configuration move independently:

graph TD
    A[Main Repository] --> B[Worktree 1
SPEC-AUTH-001
Claude Opus]
    A --> C[Worktree 2
SPEC-AUTH-002
GLM 5]
    A --> D[Worktree 3
SPEC-AUTH-003
Claude Sonnet]

    B --> E[Independent work]
    C --> F[Independent work]
    D --> G[Independent work]

The worktrees MoAI-ADK deals with come in two layers. Both ultimately ride on top of git worktree (the underlying mechanism by which one git repository owns multiple working directories), but who creates them, where they live, and how long they last differ. Knowing this difference keeps “which worktree am I working in right now?” from getting confused.

1. L1 — .claude/worktrees/: lives inside the project directory. The Claude Code runtime creates it on its own, and when the session ends a clean-state tree is cleaned up automatically. Think of it as a session-scoped temporary space.
2. L2 — ~/.moai/worktrees/: lives outside the project, under the user’s home directory. The user opts in and MoAI creates it for SPEC-scoped parallel development, reusing the same tree across the run and sync phases. Disposal requires the user to run moai worktree done explicitly.

The short diagram below captures the location and the actor behind each layer at a glance. The deeper create/dispose lifecycle and the isolation: worktree behavior are covered in the platform-basics worktree doc.

flowchart TD
    Repo[One git repository
shared .git object database]
    Repo --> L1[L1 — .claude/worktrees/
inside the project, session-scoped temporary]
    Repo --> L2[L2 — ~/.moai/worktrees/
outside the project, SPEC-scoped persistent]
    L1 --> Who1[Created autonomously by the Claude Code runtime]
    L2 --> Who2[Created by MoAI on user opt-in]

The key is the separation of sharing and isolation. The repository’s history and remote are managed together in one place, while the working directory and the LLM configuration tied to it are split completely per tree. So no matter which worktree you commit in, the other worktrees recognize that commit immediately, and branches do not tangle. On top of that, MoAI-ADK layers an entry switch (moai cc · moai glm · moai cg) that bundles “which worktree to enter” and “which LLM mode to run” into a single action.

MoAI-ADK development with Worktree flows through three phases:

flowchart TD
    subgraph Phase1["Phase 1: Plan (Terminal 1, main checkout)"]
        A1["moai plan
feature description"] --> A2[SPEC document created]
        A2 --> A3[Implementation scope fixed]
    end

    subgraph Phase2["Phase 2: Implement (Terminals 2, 3, 4...)"]
        B1["moai glm -w SPEC-AUTH-001"] --> B2[Worktree created and entered]
        B2 --> B3["moai run SPEC-ID"]
        B3 --> B4["moai sync SPEC-ID"]
    end

    subgraph Phase3["Phase 3: Merge & Cleanup"]
        C1[merge into base via
git merge or PR] --> C2[moai worktree done branch]
        C2 --> C3[Remove worktree]
        C3 --> C4[Optional: delete branch]
    end

    Phase1 --> Phase2
    Phase2 --> Phase3

Reasoning quality decides the outcome of the planning phase, so the SPEC document is authored with a Claude (Opus-class) model. This phase runs in the main checkout as it is:

> /moai plan "Add authentication system"

Outputs:

• .moai/specs/SPEC-AUTH-001/spec.md
• The SPEC ID to use in the implementation phase

The implementation phase is high-volume, but the SPEC has already set the direction — so a cheap model like GLM does the job perfectly well. Entering the worktree is the launcher’s job, via the -w flag on moai cc, moai glm, and moai cg. If no worktree by that name exists, it is created on the spot:

# New terminal: create the worktree and enter it with the GLM backend
$ moai glm -w SPEC-AUTH-001

# Start developing right inside the session you entered
> /moai run SPEC-AUTH-001
> /moai sync SPEC-AUTH-001

To open one more worktree while keeping the current session, add --spawn. It comes up in a new tmux window and the original window stays as it is:

$ moai glm -w SPEC-AUTH-002 --spawn

Advantages:

• Completely isolated working environment
• GLM cost efficiency (for the size of the savings, see CG Mode)
• Unlimited parallel development without conflicts

moai worktree done feature/SPEC-AUTH-001                    # worktree cleanup (merge/push done separately via git)
moai worktree done feature/SPEC-AUTH-001 --delete-branch    # cleanup + delete local branch

Entering a worktree and listing worktrees are not moai worktree’s job. The launcher handles entry; git handles listing:

moai worktree manages the worktrees once they exist:

Each SPEC keeps an independent Git state:

graph TD
    subgraph Main["Main Repository (main)"]
        M1[.moai/specs/]
        M2[Synced with remote]
    end

    subgraph WT1["Worktree 1 (SPEC-AUTH-001)"]
        W1A[feature/SPEC-AUTH-001]
        W1B[Independent working directory]
        W1C[Separate .moai/ configuration]
    end

    subgraph WT2["Worktree 2 (SPEC-AUTH-002)"]
        W2A[feature/SPEC-AUTH-002]
        W2B[Independent working directory]
        W2C[Separate .moai/ configuration]
    end

    Main -.-> WT1
    Main -.-> WT2

Advantages:

• Commit independently in each Worktree
• Work without cross-branch conflicts
• Only completed SPECs are merged into main

Each Worktree gets its own LLM execution mode. Three terminals can run differently — moai cc (Claude only), moai glm (GLM only), and moai cg (Claude leader + GLM worker hybrid) — without interfering with each other:

sequenceDiagram
    participant T1 as Terminal 1
Worktree 1
    participant T2 as Terminal 2
Worktree 2
    participant T3 as Terminal 3
Worktree 3
    participant Main as Main Repository

    T1->>T1: moai cc (Claude)
    Note over T1: Planning with a
high-reasoning model

    T2->>T2: moai glm
    Note over T2: Implementing with a
low-cost model

    T3->>T3: moai cg
    Note over T3: Hybrid balancing
quality and cost

    par Parallel work
        T1->>Main: Plan work
        T2->>Main: Implement work
        T3->>Main: Implement work
    end

    Main-->>T1: Only completed SPECs merged
    Main-->>T2: Only completed SPECs merged
    Main-->>T3: Only completed SPECs merged

You can run multiple SPECs at the same time:

# Terminal 1: plan SPEC-AUTH-001 (main checkout)
> /moai plan "Authentication system"

# Terminal 2: implement SPEC-AUTH-002 (GLM)
$ moai glm -w SPEC-AUTH-002
> /moai run SPEC-AUTH-002

# Terminal 3: implement SPEC-AUTH-003 (GLM)
$ moai glm -w SPEC-AUTH-003
> /moai run SPEC-AUTH-003

# Terminal 4: document SPEC-AUTH-004 (Claude)
$ moai cc -w SPEC-AUTH-004
> /moai sync SPEC-AUTH-004

Only completed SPECs are merged into the main branch:

flowchart TD
    subgraph Development["Worktrees in development"]
        D1[SPEC-AUTH-001
In progress]
        D2[SPEC-AUTH-002
In progress]
        D3[SPEC-AUTH-003
Completed]
    end

    subgraph Main["Main Repository"]
        M[main branch]
    end

    D3 -->|clean up with done after git merge/PR| M
    D1 -.->|Not yet complete| M
    D2 -.->|Not yet complete| M

This is what working across multiple terminals looks like. Each worktree is fully isolated so parallel work proceeds without conflicts — that is the heart of the Agentic Harness. The ability to assign the right model to each phase is the Tokenomics benefit that comes with it:

graph TD
    subgraph Terminal1["Terminal 1: Planning"]
        T1A["moai plan"]
        T1B[Claude Opus
high cost / high quality]
        T1C[SPEC document created]
    end

    subgraph Terminal2["Terminal 2: Implementing"]
        T2A["moai glm -w
SPEC-AUTH-001"]
        T2B[low-cost backend]
        T2C["moai run
DDD implementation"]
    end

    subgraph Terminal3["Terminal 3: Implementing"]
        T3A["moai glm -w
SPEC-AUTH-002"]
        T3B[low-cost backend]
        T3C["moai run
DDD implementation"]
    end

    subgraph Terminal4["Terminal 4: Documenting"]
        T4A["moai cc -w
SPEC-AUTH-003"]
        T4B[Claude backend]
        T4C["moai sync
documentation"]
    end

    T1C --> T2A
    T1C --> T3A
    T1C --> T4A

• Complete Guide — every Worktree command and detailed usage
• Real-World Examples — usage scenarios from real projects
• FAQ — frequently asked questions and troubleshooting

• MoAI-ADK Documentation
• SPEC System
• DDD Workflow