07. Parallel Work
Git worktrees
A git worktree is a second checkout of the same repository. Each Matcha session that uses one has its own files, so parallel assistants do not overwrite each other's uncommitted work and you do not need to stash.
matcha worktree manages those checkouts. It does not start a conversation. /fork copies a conversation; it only creates a worktree when you ask.
When to use a worktree
Use a worktree when two sessions (or a parent and a sub-assistant) will edit files at the same time:
- One session implements a feature while another stays on
main. - An experiment can fail without dirtying the directory you still have open.
- When the work is good, merge or cherry-pick like any other branch.
If you only need a second conversation with the same files, /fork without a worktree is enough — and cheaper.
Start a session in a worktree
From the welcome screen (inside a git repo), press Ctrl+W to open the New Worktree dialog, name the checkout, and start there.
From anywhere in the TUI, press Ctrl+N twice to confirm a new session, then choose the worktree option.
From the shell, pass --worktree with =. Without =, clap treats the next token as the worktree name and the prompt is lost:
matcha --worktree=my-feature "refactor the auth module"--worktree / -w also accepts a bare flag (Matcha names the checkout). --worktree-ref / --ref pins the base to a branch, tag, or commit; the default is the source checkout's current HEAD.
Resume an existing session in a fresh worktree:
matcha -w -r <session-id>`/fork` versus a worktree session
/fork | Session started with --worktree / Ctrl+W | |
|---|---|---|
| History | Copy of the current conversation | New (or resumed) session; empty unless you resume |
| Files | Same cwd unless --worktree / Yes | Always a new checkout |
| When to use | Split thinking or try a second approach with shared context | Isolate file edits from the start |
A fork with --worktree is both: copied history and an isolated checkout. See Fork a session.
Sub-assistants can also take isolation: worktree so a child edits a private checkout. That is still a child of the current session, not a dashboard peer. See Sub-assistants and personas.
Manage checkouts: `matcha worktree`
These subcommands talk to Matcha's worktree registry. They do not open the TUI.
matcha worktree list # alias: ls
matcha worktree list --json
matcha worktree list --repo <name>
matcha worktree list --type session,fork,subagent
matcha worktree list --all
matcha worktree show <id-or-path>
matcha worktree rm <id-or-path> […]
matcha worktree rm --dry-run <id-or-path>
matcha worktree rm -f <id-or-path> # force
matcha worktree gc # alias: prune
matcha worktree gc --max-age 7d --dry-run
matcha worktree gc --max-age 7d # then without --dry-run
matcha worktree db stats
matcha worktree db path
matcha worktree db rebuild--type filters registry kinds such as session, fork, subagent, manual, ab, and pool.
gc without --max-age expires nothing. It only visits worktrees the registry tracks. Untracked directories (shown by matcha du as untracked) are never gc'd; remove one with matcha worktree rm after a --dry-run. Neither gc nor rm inspects uncommitted or unpushed work — read the preview first.
Disk use of ~/.matcha (including worktrees) is matcha du / matcha disk-usage. Worktree clones can share storage with the source, so the reported total can exceed the space actually used.
Config hints
[hints] fork_worktree_mode and [hints] new_session_worktree_mode control whether /fork and /new ask about a worktree (ask, always, never). The legacy key is [hints] worktree_mode. /fork defaults to **ask**; /new defaults to **never** (no popup) when those keys are unset.
Not in this build
matcha workspace is a hidden CLI and is not a worktree manager. workspace_hub_exposure is disabled. Use local sessions, /dashboard, and matcha worktree instead. Do not set test-only environment overrides to turn a hub on.