Skip to main content
A workspace is a working directory with its own Mirror agent and conversation. Start Mirror in your existing checkout, then create workspaces when tasks need separate file edits.
  • The first workspace uses the directory and branch you started from.
  • You can also start in a plain directory.
  • Creating additional workspaces requires Git or Jujutsu.

​
Create a workspace

In a Git repository whose origin remote has a main branch, run:
Mirror creates the checkout in the background:
  1. Fetches origin/main.
  2. Creates the branch mirror/parser-tests.
  3. Checks it out under ~/.mirror/worktrees/<repository-and-hash>/parser-tests.
Your original workspace stays selected. Switch to the new workspace when it appears.
  • The new workspace starts a fresh conversation.
  • It inherits the source workspace’s model, reasoning effort, and approval mode.
  • If you launched Mirror in a subdirectory, it uses the corresponding subdirectory in the new checkout. Start from the repository root if that subdirectory does not exist on origin/main.
The new checkout starts at the fetched main branch. Your current branch, uncommitted edits, and untracked files are not copied into it.
Omit the name to let Mirror choose one, or use a short task name such as parser-tests or review-api.
  • Use 1 to 64 ASCII letters, numbers, dots, dashes, or underscores.
  • Start with a letter or number.
  • Do not include .. or end with . or .lock.
For Jujutsu, Mirror fetches main from origin and creates a workspace at main@origin.

​
Find and switch workspaces

Run /workspaces to open the picker. Each entry shows its name, agent status, and directory. The active entry is marked (current).
Mirror workspace picker showing the original checkout and two separate task workspaces

The workspace picker in a demonstration project with temporary checkout paths.

  • Type to search by workspace name or directory.
  • Use the arrow keys or Tab and Shift+Tab to move the highlight.
  • Press Enter to switch, or Escape to close the picker.
Outside a menu, use these shortcuts:
  • With at least two workspaces, the footer shows the selected workspace and its position, such as 2/3.
  • Run /status to check the active working directory, conversation ID, model, and reasoning effort before sending a task.
Mirror in the add-tests workspace with its branch, selected workspace indicator, and a workspace-specific reminder

The selected task workspace has its own agent and reminder text. This is an isolated example session.

​
Agent status

The picker and workspace footer show what each agent is doing:
  • Switching preserves each conversation and any running turn.
  • An agent can continue working while you use another workspace in the same Mirror process.
  • Selecting a workspace clears its unread indicator.

​
Run two tasks in parallel

For example, let one agent add tests while another investigates the current implementation:
  1. Run /worktree parser-tests from the original checkout.
  2. Open /workspaces, select parser-tests, and press Enter.
  3. Give it a task:
  4. Switch back to the original checkout and send a separate task:
  5. Return to parser-tests to review its diff and test results. If its status is !, approve or reject the waiting tool call there.
The two agents have separate conversations and file trees. They share the repository’s history, so use your normal version-control workflow to bring completed changes together.

​
Names and settings

To give the selected workspace a clearer display name:
  • The alias changes the picker and footer labels.
  • The Git branch, Jujutsu workspace name, directory, and conversation keep their existing names.
Each workspace remembers its alias, model, reasoning effort, and approval mode in ~/.mirror/cli.db. When Mirror starts, the first workspace uses the approval mode saved in ~/.mirror/config.json. Select a workspace to change its settings independently:
  • Extension enablement comes from the shared user configuration.
  • A loaded extension can participate in multiple workspaces while keeping separate state in each one. See extensions.

​
Return to existing work

When you start Mirror again:
  • Mirror rediscovers managed checkouts belonging to the repository.
  • The workspace list includes the launch checkout and those managed checkouts by default.
A normal launch starts fresh conversations. To continue recent conversations:
  • Mirror selects the most recent saved conversation for each workspace’s working directory.
  • A discovered workspace’s saved agent starts when you select it.
  • Use /resume within a workspace to choose a different conversation.
Quitting Mirror closes its agents. They do not keep running after the process exits.

​
Show other existing checkouts

To include Git worktrees or Jujutsu workspaces created outside Mirror, add this setting to ~/.mirror/config.json. Preserve any existing extension settings in the file.

​
Review and integrate changes

The repository footer shows the branch or revision, changed-file count, and added/deleted lines. In Git:
  • The summary counts tracked staged and unstaged changes against HEAD.
  • It excludes untracked files and committed differences from main.
Review the task checkout before integrating it. For the parser-tests example:
  1. Review changes from that checkout in another terminal, or ask its agent to run these commands:
  2. Run the relevant tests, then commit the files you reviewed.
  3. When your target checkout is ready, integrate the completed branch there:
Use a pull request or cherry-pick instead if that fits your repository’s workflow. In Jujutsu, use your usual review and integration commands.

​
Remove a workspace

  1. Select the completed workspace.
  2. Preserve its work.
  3. Run:
/drop force-removes a Mirror-managed checkout, including uncommitted files, without another confirmation. Commit or otherwise preserve anything you want to keep first.
  • Mirror refuses to remove the primary checkout or the only available workspace.
  • Removing an unmanaged checkout asks for confirmation and names its directory.
Dropping a Git worktree:
  • Leaves its branch and saved conversations in place.
  • Removes the workspace’s alias and preferences.
  • Reusing the workspace name can fail while its Git branch still exists.