Worktrees

Metaphor gives each task its own Git worktree.

A worktree is a separate working directory for a repository. It keeps a task’s changes isolated from your main checkout and from other tasks working on the same repository.

How Metaphor uses worktrees

When you create a task, Metaphor creates a worktree for the repository you selected.

The agent works inside that worktree instead of your main checkout, keeping the task’s files and changes separate from your other work.

If you continue the same task with another prompt or switch agents, Metaphor keeps using the same worktree. The existing changes stay with the task.

A new task gets its own worktree, even when it uses the same repository.

Work on tasks in parallel

Because each task has its own worktree, multiple tasks can work on the same repository at the same time without mixing their changes.

For example, one task can fix a bug while another builds a feature. Each agent works in its own worktree, and each task keeps its own changes.

You don’t need to create worktrees yourself. Metaphor manages them with the task.

Work locally

You can open a task’s worktree in your editor or IDE to run, test, or modify the agent’s work.

Changes you make locally appear in the task’s diff in Metaphor. When you continue the task, the agent works from those changes too.

Open from Files

Open Files from the right sidebar, then right-click a file and choose the editor or IDE you want to use.

You can open the worktree in apps such as Finder, VS Code, Cursor, Zed, or Xcode.

Open from the terminal

The terminal in Metaphor opens in the current task’s worktree.

Run pwd to see the worktree’s location:

pwd

Open the current worktree in your preferred editor or IDE:

Xcode

open -a Xcode .

VS Code

code .

Cursor

cursor .

Zed

zed .

Changes you make from your editor or IDE stay in the same task worktree and appear in Metaphor’s diff.

Archive a worktree

Metaphor keeps a worktree until you archive its task, even after the task is finished or its pull request is merged.

When you no longer need the worktree, hover over the task in the sidebar and select Archive.

Metaphor removes the worktree and the task from your sidebar.