Worktree Isolation
Relevant source files
The following files were used as context for generating this wiki page:
Worktree Isolation is a core architectural feature of Morty that enables parallel execution of AI coding agents. By leveraging Git worktrees, the system allows multiple AI agents to operate simultaneously in separate, isolated file system directories, each associated with its own Git branch. This mechanism prevents file access conflicts and state contamination that would occur if multiple agents attempted to modify a single working directory.
This system ensures that each task defined in a PRD or task list is implemented in a "clean room" environment. Once an agent completes its task within its isolated worktree, the resulting changes are merged back into the base branch, often involving AI-assisted conflict resolution to handle overlapping changes from concurrent agents.
Sources: landing/components/features.tsx:21-25, morty.sh:1017-1019, cli/src/execution/parallel.ts:133-135
Architecture and Lifecycle
The isolation lifecycle is managed through a sequence of directory creation, environment replication, task execution, and automated cleanup.
Parallel Agent Workflow
When parallel execution is triggered (via --parallel), Morty initializes a base directory for worktrees, typically located at .morty-worktrees or a temporary path. For each task in a batch, a dedicated agent worktree is spawned.
The diagram shows how agents are branched out into isolated environments before converging back during the merge phase.
Sources: morty.sh:1034-1045, cli/src/execution/parallel.ts:145-160
Key Components
| Component | Description | Reference |
|---|---|---|
worktreeBase | The parent directory for all active agent worktrees (e.g., .morty-worktrees). | cli/src/git/worktree.ts:80-86 |
agentNum | A unique identifier for the agent, used in directory and branch naming. | morty.sh:910-911 |
branchName | A task-specific branch (e.g., morty/agent-1-...) created using git worktree add -B. | cli/src/git/worktree.ts:36-40 |
originalDir | The root project directory where the main Git process and configuration reside. | morty.sh:913-915 |
Worktree Management Logic
The management of worktrees involves atomic creation to avoid race conditions and conditional cleanup to preserve work in case of failures.
Creation and Initialization
The function createAgentWorktree generates a unique identifier (timestamp + random suffix) to prevent branch collisions. It uses the atomic git worktree add -B flag, which creates or resets the branch and sets up the directory in one operation.
This sequence ensures a clean, isolated environment is prepared before the AI agent begins its task.
Sources: cli/src/git/worktree.ts:25-45, cli/src/execution/parallel.ts:50-70
Cleanup and Retention
Cleanup is handled by cleanupAgentWorktree. A critical safety check is performed: if a worktree contains uncommitted changes (checked via git status), the system leaves the directory in place to prevent data loss. Otherwise, the worktree is forcibly removed, though the associated Git branch is preserved for the merge phase.
Sources: cli/src/git/worktree.ts:53-76, morty.sh:966-978
Integration and Merging
Once worktree execution is complete, Morty enters a "Merge Phase" to reconcile changes from isolated branches.
Parallel Groups and Integration Branches
In YAML-based task sources, parallel_group identifiers allow users to control execution order. Morty uses "Integration Branches" (morty/integration-group-N) to aggregate work from one group before the next group starts, ensuring agents in later groups see the completed work of previous ones.
The diagram represents the sequential flow between parallelized groups using integration branches as sync points.
Sources: morty.sh:1193-1220, cli/src/git/merge.ts:64-83
AI-Assisted Conflict Resolution
If conflicts arise during the merge of isolated branches, Morty invokes the AI engine with a specific resolution prompt. The AI is tasked with reading conflict markers, intelligently combining changes, and completing the merge via git add and git commit.
Sources: cli/src/execution/parallel.ts:269-285, morty.sh:1300-1325
Configuration Summary
| Option | Type | Default | Description |
|---|---|---|---|
parallel | boolean | false | Enables worktree-based parallel execution. |
maxParallel | number | 3 | Maximum number of concurrent agent worktrees. |
skipMerge | boolean | false | If true, branches are left unmerged after completion. |
worktreeBase | string | .morty-worktrees | Directory where worktrees are created. |
Sources: cli/src/config/types.ts:98-125, morty.sh:42-43
Summary
Worktree Isolation provides a robust mechanism for scaling AI development within a single repository. By containerizing agent environments at the Git level, Morty eliminates file-locking issues and allows for sophisticated parallel workflows, including group-based execution and automated conflict resolution. This architecture ensures that parallelization does not compromise the integrity of the project's source code.