/worktree uses origin when present, or the sole remote otherwise, and starts from its default branch. With no remote, it uses the local committed revision. Use /fork to carry the current conversation and working files into another workspace, or /folder <path> to open an existing directory.
Run a task in parallel
Suppose one agent is investigating a bug and you’d like another to write tests at the same time.-
Create a workspace for the new task:
Mirror creates it in the background while you keep working. A tab for it appears at the bottom of the screen.
-
Press Tab to switch to
parser-tests, then give it a task: -
Press Shift+Tab to go back to your original workspace and carry on. The
parser-testsagent keeps working. -
Its tab shows
✓when it finishes. Switch back to review its work.
What a new workspace contains
/worktree <name> fetches the remote’s default branch and creates a new checkout of it on a branch called mirror/<name>. Mirror keeps the checkout under ~/.mirror/worktrees/. If fetching fails, it uses the cached default branch or local committed revision and shows a warning. If there are several remotes and none is named origin, configure origin or create a checkout yourself and open it with /folder.
Local edits and untracked files aren’t copied. A checkout based on the remote’s default branch also excludes your unpushed commits. If Mirror falls back to the local committed revision, those commits may be included.
parser-tests or review-api, or omit it and Mirror picks one. A name has up to 64 letters, digits, ., -, and _, starts with a letter or digit, and can’t contain .. or end in . or .lock. Mirror creates one workspace at a time.
Fork the current workspace
Use/fork [name] when you want to try another approach with the conversation and files you already have:
Forking requires an idle local workspace in the repository where you launched Mirror. Wait for the turn and queued messages to finish first. Hosted and sandbox workspaces can’t be forked.
Ignored files, submodule contents, and nested repositories aren’t copied. In Git, copied working changes are unstaged. Resolve Jujutsu conflicts before forking. Stop other processes that are writing to the checkout while Mirror captures it, since the capture isn’t atomic.
A fork captures the files as they are now; it doesn’t restore files from an earlier message. If creation fails, inspect the conversation ID and path in the error before retrying, since a partial checkout may remain.
Switch between workspaces
Once you have more than one workspace, a row of tabs at the bottom of the screen shows each one with its agent’s status. The selected workspace is highlighted.
The workspace list, with three workspaces in a demonstration project.
*.
Switching never stops an agent. Each one keeps its conversation, and any turn in progress keeps running while you work elsewhere.
Agent status
With manual approval, an agent that needs approval waits at
! until you switch to it and answer.
Review and merge the work
Each workspace is an ordinary checkout on its own branch, so you review and merge its work with your usual tools. The line above the tabs shows the workspace’s branch and how many tracked files have uncommitted changes. To review theparser-tests work, either ask its agent to show you, or run these in another terminal from its directory:
mirror/parser-tests branch. Then merge that branch into your target branch, or open a pull request from it:
Remove a workspace
Run/close to close a workspace while keeping its files. Directories opened with /folder can’t be deleted with /drop.
When you’ve kept the work you want, select the workspace and run /drop. Mirror removes the checkout, closes its agent, and switches you to another workspace.
The mirror/<name> branch and the workspace’s saved conversations remain. To reuse the name for a new workspace, delete the old branch first.
You can’t drop the repository’s main checkout (the one you cloned) or your only workspace. /drop doesn’t run while the agent is working; wait or press Escape first.
Rename a workspace
/rename changes the name shown in the tabs and the workspace list:
Workspace settings
Each workspace remembers its own model, reasoning effort, and approval mode. Change them in the workspace with/model, /effort, or /approvals, and other workspaces aren’t affected. Mirror stores these settings in ~/.mirror/cli.db.
An explicit --approval-mode overrides the launch workspace’s saved mode. Otherwise, that workspace keeps its own preference, falling back to the approval mode in ~/.mirror/config.json.
Come back to your workspaces
When you start Mirror again in the same repository, it finds the workspaces it created earlier and shows them as tabs. By default each starts a new conversation. To pick up where you left off, start Mirror with:/resume in that workspace.
Quitting Mirror stops every agent. Nothing keeps running in the background after you exit.
Show checkouts created outside Mirror
Mirror shows the checkout you launched from and the workspaces it created. To include Git worktrees or Jujutsu workspaces you created yourself, add this to~/.mirror/config.json, keeping any settings already there:
~/.mirror/config.json
/close to close a checkout Mirror didn’t create; /drop can’t delete folder workspaces.
Jujutsu
In a Jujutsu repository,/worktree <name> fetches the selected remote’s default branch and adds a Jujutsu workspace called <name> at that revision. If fetching fails, it uses the cached default branch or local committed revision and shows a warning. The jj command must be installed. The repository line shows the change ID and any bookmarks. Use your usual Jujutsu commands to review and integrate the work.
Sandbox workspaces
Run/sandbox [name] to choose an empty workspace or a copy of the current repository’s committed revision. Mirror stores the clone under ~/.mirror/sandboxes/<name>. Its file and shell tools run in a microVM; extensions and local MCP servers still run on the host. Setup asks before installing the runtime or downloading an image.
Sandbox workspaces require macOS on Apple Silicon, or Linux with access to /dev/kvm. Quitting Mirror stops the VMs; reopening it restarts them. /drop deletes the sandbox’s VM and clone after confirmation. Copy or commit anything you want to keep first.
Workspace tags
Use/tag to choose or customize a workspace icon, or press Ctrl+S to cycle the current tag. Tags help you distinguish workspaces in the tabs and the workspace list.