07. Parallel Work
Fork a session
/fork copies the current conversation into a peer top-level session in this Matcha CLI process. The child starts from the same history, then runs on its own. File changes stay in the current checkout unless you also ask for a git worktree.
This is not a remote assistant, and it is not matcha worktree. Cloud Agent (cloud_agent) is unavailable in this build. A worktree is a separate git checkout; /fork is a conversation split that may create one.
When to fork
Use a fork when you want a second line of work without leaving the session you already have:
- Try another approach (
/fork try the async rewrite) while the original session keeps the first plan. - Hand a sibling the same context so it can research or implement in parallel.
- Keep one session talking to you and another executing a long task.
A new session (/new, Ctrl+N) starts empty. A fork starts informed.
How `/fork` works
/fork is session-scoped. Run it from inside an active conversation, not from the welcome screen.
/fork [--worktree|--no-worktree] [directive]| You type | What happens |
|---|---|
/fork | Opens a peer session with a copy of this history and no first prompt. |
/fork investigate the rate-limit path | Same copy, then sends that text as the child's first prompt. |
/fork --worktree try the async approach | Copy history and put the child in a new isolated git worktree. |
/fork --no-worktree quick check | Copy history in the current working directory. |
--worktree and --no-worktree are mutually exclusive. Unknown tokens after the flags become the directive, so /fork --foo bar is a first prompt of --foo bar, not an error.
The worktree question
If you omit both flags and the session is inside a git repository, Matcha asks whether the fork should get its own worktree:
- **Yes** — isolated checkout.
- **No** — same
cwdas the parent (both sessions can edit the same files). - **Always worktree** / **Never worktree** — remember the choice in
[hints] fork_worktree_mode(always/never). Reset that key toaskto be prompted again.
Default when the key is unset: **ask** on /fork. If you are not in a git repository, Matcha skips the question and forks in place. /fork --worktree outside a git repo is refused with a toast.
The parent scrollback records Forked or Forked: <directive>. Matcha then switches you to the child. Use the assistant dashboard (/dashboard or Ctrl+\) to jump back.
What a fork is not
/fork | New session in a worktree | matcha worktree | |
|---|---|---|---|
| Copies this conversation | Yes | No | No |
| Creates a git checkout | Only with --worktree / Yes | Yes (matcha --worktree=…, Ctrl+W) | No — it lists, shows, removes, and gc's checkouts Matcha already made |
| Lives on this machine | Yes | Yes | Yes |
| Cloud Agent | Unavailable | Unavailable | Unavailable |
For isolated checkouts, lifecycle, and disk cleanup, see Git worktrees.
Headless history split is a different entry: matcha --resume <id> --fork-session copies a saved session into a new session ID. That is not the TUI /fork command.
Limits
/forkonly works inside a loaded session. If the session is still being created, Matcha toasts and does nothing.- A fork is a **peer**, not a child sub-assistant. Sub-assistants are spawned by the assistant (
spawn_subagent) and nest one level under a parent; see Sub-assistants and personas. - Cloud Agent (
cloud_agent) is fail-closed. There is no remote path to run this fork in an official cloud.