Mirror CLI: models and parallel worktrees

Mirror is Reflection's terminal coding harness. It can read and edit files and run commands; this guide covers its CLI workflow, not model training. Beam is one model route, while other providers have different authentication and tool-call contracts. Official CLI overview

Native Windows is not supported. The table does not establish that an arbitrary WSL, container or remote setup is supported; validate that environment separately. A plain directory can be used, but it does not supply repository worktree management. Requirements

Keep the first task small enough to inspect. If you need an architecture explanation first, use our Agent Harness Engineering resource. If the objective is isolation from untrusted code, use the sandbox guide to understand that separate requirement; changing a checkout does not meet it.

Install on your own supported host

The official package is reflection-mirror; its executable is mirror. The PyPI package named mirror is unrelated. Release wheels include the native agent and ripgrep, so the documented wheel path does not require a Rust build. Install uv through its official instructions if you do not already have it; this guide did not install either tool. Installation

uv tool install reflection-mirror
mirror --version

Record the reported version. These unpinned install instructions follow the publisher's current package, not a promise of a fixed future release. If the command is missing, the documentation suggests uv tool update-shell, then restarting the shell. Review downloads and upgrades in your own environment before accepting them. Install and updates

Connect Reflection, then choose the available model

Start in the intended project. The explicit approval flag selects manual approval even if auto mode was saved earlier; explicit choices are remembered. Approval configuration

cd /path/to/your/project
mirror --api reflection --approval-mode approve

Replace the directory placeholder first. Use Mirror's masked sign-in prompt or an existing secret-management workflow for REFLECTION_API_KEY; do not paste a real key into the example, an issue or a transcript. Reflection requests use https://api.reflection.ai/openai/v1. Use /model to confirm the model actually available to your account, and /status to confirm the directory. We do not invent a Beam model ID from its marketing name. Reflection sign-in and models

Exporting a provider key does not select that provider. A saved workspace selection can also affect startup. Check the active route rather than assuming that a new environment variable changed it. Explicit --api and --base-url override a matching model entry; without an explicit model or API, startup can restore a saved selection. Configuration precedence

These are the documented CLI routes, not proof of access to every model or subscription. For the Codex plan route, the guide specifies an existing Codex login and reads ~/.codex/auth.json by default; MIRROR_CODEX_AUTH_PATH selects another file. Do not copy another person's credential file. Provider contract

A self-hosted endpoint must already exist

mirror --api openai-chat-completions \
  --base-url http://127.0.0.1:8000/v1 \
  --model your-model-name --approval-mode approve

Replace the example address and model name with your server's actual contract. Mirror does not start the model server for you. The endpoint must implement the tool calls Mirror needs: a successful text response alone does not establish tool compatibility. This localhost example reaches the machine running Mirror; it is not a hosted service provided by Agent Skills Hub. Custom endpoint

For reusable choices, ~/.mirror/models.json requires id and label; api and base_url are optional routing fields. Keep API keys out of model entries and endpoint URLs. Edit only the intended entry in your existing configuration; do not overwrite a working catalog to follow a tutorial. Model configuration

Open-source software does not mean free model usage. Provider inference, plan limits and a self-hosted server have separate costs. Check the selected provider's account terms and usage before enabling parallel tasks; no universal dollar estimate or included quota is established here. To inspect only the interface, the documented mirror --showcase plays a synthetic conversation without model calls or real tools. That demonstrates the UI, not repository execution. Showcase boundary

Before sending a task, inspect the working directory and the approval mode in /settings → CLI mode. By default, local tools run with your account's permissions; manual approval does not restrict file or network access. Model requests can send relevant file contents, instructions and tool results to the selected provider. Use a repository whose contents you are allowed to share. Local data and safety

Suggested first-task prompt — editorial example, not a tested result:

Read only. Explain how this repository starts and where its tests are defined.
Cite exact file paths and the relevant configuration for each statement.
Do not edit files, install packages, run tests, contact services or commit.
List the test command you would propose and any missing prerequisites.
Mark anything you cannot verify as unknown.

A prompt constrains the requested task; it is not an enforcement boundary. Inspect each tool request before approval. Reject an unexpected write or external action. Escape interrupts active work; a menu may handle it first. Verify that activity actually stopped before revising the task. Working with Mirror

Accept this first result only when the cited files exist, their contents support the explanation, and the proposed command matches repository scripts. Check that no files changed. When you later authorize a modification, name the allowed files, expected behavior and one relevant test. Preserve the actual test command, exit status and output; a confident summary is not a test receipt.

This acceptance checklist is our review procedure. We did not run Mirror, connect a provider or execute this prompt for the article.

Within Mirror, enter the slash command below; it is not a shell command:

/worktree parser-check

The documented starting point is the default branch of origin (or the sole remote). Fetching is best-effort; offline it may use a cached default or local committed revision. Local uncommitted edits are not copied. If the second task depends on an edit you have not committed, the new agent may not see it. Preserve the edit and deliberately choose a suitable starting state before assigning dependent work. Parallel worktrees

Check /status and the checkout itself. These ordinary Git checks are editorial verification commands for a trusted Git checkout; they do not create, fetch or alter commits:

git rev-parse --show-toplevel
git status --short --branch
git log -1 --oneline

Give the second agent an independent task with its own allowed files. Use Tab / Shift+Tab to switch worktree tabs or /workspaces to pick one. Agents keep working when you switch tabs. Each worktree has its own conversation, model and approval settings, so check them in every workspace. A tab switch is neither a stop command nor permission to merge its changes. Workspace behavior

Before integrating results, inspect both diffs, compare their starting revisions, resolve overlap deliberately and rerun the relevant validation in the destination checkout. A finished agent conversation does not merge, push or deploy a change for you. Keep those actions subject to your project's authorization.

When a worktree is the wrong boundary

A normal worktree separates repository files, not host permissions or secrets. Mirror also documents /sandbox workspaces using a microVM, with separate host requirements and setup prompts for runtime/image installation. We did not install or test that path. Even with sandbox workspaces, extensions and local MCP servers can still run on the host. Do not infer that every tool is isolated, and do not treat a README claim as a security certification. Sandbox workspaces · Host-side boundaries

To return to the most recent conversation in each worktree, start from the intended project:

cd /path/to/your/project
mirror --continue

/resume browses saved conversations; /resume <id-or-prefix> selects one. /clear starts a fresh conversation. /rewind branches conversation history; it does not undo file changes. Recheck the actual checkout before acting on a resumed transcript. Save a short checkpoint containing task, directory, revision, allowed files, actual changes/tests and unresolved actions. Conversations and context

The documented update behavior also matters for reproducibility: --no-update skips checking but may still select a newer cached release; MIRROR_SKIP_UPDATE=1 bypasses both checks and cached releases. Record the actual version. An older executable may not understand newer saved state, so reinstalling an older package is not a database rollback. Back up needed local state with Mirror stopped before changing versions. Updates · Recovery limits

Conversation databases, logs and saved credentials live under ~/.mirror/. Do not publish that directory as a troubleshooting attachment. /logout removes the saved Reflection key but does not revoke it at the provider or cancel requests already in flight; an environment key needs separate removal from your shell. Remembered command prefixes can contain plaintext arguments: do not save a rule containing a secret. Sign-in lifecycle · Approval storage