> ## Documentation Index
> Fetch the complete documentation index at: https://developers.reflection.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirror workspaces

> Run parallel tasks in separate checkouts, switch agents, and preserve completed work

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.

```bash theme={null}
cd /path/to/project
mirror
```

* 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:

```text theme={null}
/worktree parser-tests
```

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`.

<Note>
  The new checkout starts at the fetched main branch. Your current branch, uncommitted edits, and untracked files are not copied into it.
</Note>

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)`.

<Frame caption="The workspace picker in a demonstration project with temporary checkout paths.">
  <img src="https://mintcdn.com/reflection-ai/KgZ1lXVu3m3QzQyh/images/mirror/workspaces-picker.jpg?fit=max&auto=format&n=KgZ1lXVu3m3QzQyh&q=85&s=dc4a1c15d00054360b163ee65a5bace1" alt="Mirror workspace picker showing the original checkout and two separate task workspaces" width="1038" height="459" data-path="images/mirror/workspaces-picker.jpg" />
</Frame>

* 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:

| Key | Action |
| - | - |
| `Tab` | Switch to the next workspace. |
| `Shift+Tab` | Switch to the previous workspace. |
| `Ctrl+1` through `Ctrl+9` | Select by position, in terminals that support these key sequences. |

* 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.

<Frame caption="The selected task workspace has its own agent and reminder text. This is an isolated example session.">
  <img src="https://mintcdn.com/reflection-ai/KgZ1lXVu3m3QzQyh/images/mirror/workspace-active.jpg?fit=max&auto=format&n=KgZ1lXVu3m3QzQyh&q=85&s=d8cd519e691874c6c563a276d3f8dbd5" alt="Mirror in the add-tests workspace with its branch, selected workspace indicator, and a workspace-specific reminder" width="1038" height="389" data-path="images/mirror/workspace-active.jpg" />
</Frame>

### Agent status

The picker and workspace footer show what each agent is doing:

| Indicator | Meaning |
| - | - |
| `·` | The agent has not started. |
| `↻` | A saved conversation is waiting to resume. |
| `○` | The agent is idle. |
| `●` | The agent is running. |
| `!` | A tool-approval request needs attention. |
| `✓` | A background turn has finished with unread output. |
| `×` | The agent failed. |

* 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:

   ```text theme={null}
   Add tests for the parser's handling of blank input and malformed input.
   Run the relevant tests and report the results.
   ```

4. Switch back to the original checkout and send a separate task:

   ```text theme={null}
   Explain how the parser currently handles malformed input.
   Include the relevant functions and existing tests. Do not change files.
   ```

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:

```text theme={null}
/rename Parser tests
```

* 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:

| Setting | Command |
| - | - |
| Model | `/model` |
| Reasoning effort | `/reasoning` |
| Approval mode | `/permissions` |

* 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](/mirror-extensions#extensions-across-workspaces).

## 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:

```bash theme={null}
mirror --continue
```

* 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.

```json theme={null}
{
  "display_unmanaged_worktrees": true
}
```

## 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:

   ```bash theme={null}
   git status --short
   git diff HEAD
   ```

2. Run the relevant tests, then commit the files you reviewed.

3. When your target checkout is ready, integrate the completed branch there:

   ```bash theme={null}
   git merge mirror/parser-tests
   ```

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:

   ```text theme={null}
   /drop
   ```

<Warning>
  `/drop` force-removes a Mirror-managed checkout, including uncommitted files, without another confirmation. Commit or otherwise preserve anything you want to keep first.
</Warning>

* 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.