Skip to main content
A workspace is a directory with its own agent and conversation. Mirror starts with one, for the directory you launched it in. Add more when you want agents to work on separate tasks at the same time: each new workspace is its own checkout of the repository, so the agents can edit files and run tests without getting in each other’s way. Creating worktree workspaces needs a Git or Jujutsu repository. /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.
  1. 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.
  2. Press Tab to switch to parser-tests, then give it a task:
  3. Press Shift+Tab to go back to your original workspace and carry on. The parser-tests agent keeps working.
  4. 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.
Each workspace branches from the default branch, so several agents can work at once and you merge each branch when its work is done: The new workspace starts a fresh conversation and copies the model, reasoning effort, and approval mode of the workspace you created it from. If you launched Mirror in a subdirectory, the new agent starts in the same subdirectory of the new checkout. Start Mirror from the repository root if that subdirectory doesn’t exist on the selected base revision. Choose a short name that describes the task, such as 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:
Mirror captures the current working files, creates a new Git worktree or Jujutsu workspace, and branches the conversation into it. The new tab is selected immediately and opens idle when ready. It inherits the model, reasoning effort, and approval settings. Changes in either workspace then stay separate. 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.
Mirror's workspace list showing the original checkout and two task workspaces, each with its status and directory

The workspace list, with three workspaces in a demonstration project.

In the list, type to search by name or directory, use the arrow keys or Tab to move, and press Enter to switch. The workspace you’re in is marked *. 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 the parser-tests work, either ask its agent to show you, or run these in another terminal from its directory:
When you’re happy with the changes, commit them on the 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.
/drop deletes the checkout, including uncommitted changes, without asking first. Commit or copy anything you want to keep before you run it.
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:
The branch, directory, and conversation keep their names.

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:
Each workspace then resumes its most recent conversation when you select it. To choose a different one, use /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
The change applies straight away. Use /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.
Last modified on November 3, 2026