Quickstart

Install Mirasim#

Mirasim's primary surface is a macOS desktop app for Apple Silicon. The download page resolves the latest release for you, so the build you get there is the same build every other entry point serves.

1. Download the DMG

   Get Mirasim for macOS from the Download page. It needs an Apple Silicon (M-series) Mac on macOS 13 Ventura or later. There is no Windows or Linux GUI build.

2. Drag Mirasim into Applications, then open it

   The first launch may ask you to confirm opening an app downloaded from the internet — choose Open. Code signing and notarization depend on the credentials configured for that build, so check the release notes if macOS is unusually insistent.

3. Verify the file, if you care to (optional)

   Every release publishes SHA256SUMS covering every public download. Compare your download against it before you open anything.

shasum -a 256 ~/Downloads/Mirasim-*-arm64.dmg
# compare the hash against the matching line in SHA256SUMS

The version number in the title bar is a button. It opens the update panel — what you are running, when it last checked, and whether a new build is waiting — and a new version downloads on its own, then waits there for one click. The same panel is where Help lives, including documentation and a feedback box you can submit anonymously; anonymous means your account, email and device identifier are not attached, so nobody can reply to you either.

The setup assistant on first launch#

The first launch opens a full-window setup assistant instead of the workbench. It runs once, and there is no Skip: signing in is required before the workbench will mount. Back works on every screen after the first.

1. Sign in

   Use GitHub or Google, or have a code sent to your email. This is also where you agree to the terms and the privacy policy.

2. Redeem an invite code

   Only if your account does not already carry access. Redeeming takes effect immediately and you are never asked again; accounts that already have access never see this screen at all.

3. Install an agent

   Claude Code or Codex — one of the two is required. The assistant reports what it already found on this machine and installs what is missing.

4. Choose where quota comes from

   Your own accounts, or Mirasim's quota fallback when they run dry. This writes the default route; you can change it later in Settings. Builds that ship without the fallback skip this screen.

5. Start

   The last screen summarises what is ready on this machine and hands you the workbench.

Add a workspace and pick an agent#

Two things get you from a fresh install to working: a workspace to build in, and an agent to build with. Everything else in this guide is elaboration on those two choices.

Mirasimv0.0.121

Default

42%you@yourteam.dev

8%

checkout-api

Fix the two-pane split on narrow screens2h

Wire the export button to the render queue4h

Cache the product list between routes4h

Make the empty state explain what to do next21h

Retry failed uploads instead of dropping them21h

+ 4 more

design-system

Move the settings page behind a feature flag<1m

Give the search box a keyboard-only path4h

Stop the sidebar from scrolling with the page6d

Trim the bundle by lazy-loading the editor6d

Handle the expired-token case on refresh7d

+ 91 more

docs-site

Log slow queries with their bind parameters13d

Split the checkout form into two steps15d

infra

Round prices at display time, not in storage4h

Redraw the chart only when data changes22h

Name the exported file after the report1d

Warn before leaving a half-written draft6d

Keep the diff view in sync while typing7d

+ 16 more

mobile-app

Make the date picker respect the locale4h

Batch the write queue instead of one call each4d

Show which filters are active, not just the count5d

Fall back to the cached list when the API is down5d

Let the table remember its sort between visits6d

+ 2 more

storefront

Add dark mode toggle to settings23h

Explain the error instead of printing the code5d

Fix the two-pane split on narrow screens5d

Wire the export button to the render queue5d

Add dark mode toggle to settings5d

infra

Cache the product list between routes<1m

Make the empty state explain what to do next1h

Retry failed uploads instead of dropping them1d

Move the settings page behind a feature flag1d

Give the search box a keyboard-only path4d

+ 7 more

Add Workspace

YYou

storefront/New Session

Type a prompt — paste or drop files too

~/code/storefront

Open Terminal

storefront

Apodex/opus-4-8

high

1. 1Workspace
2. 2Agent and model
3. 3Reasoning level
4. 4Prompt box

WorkspaceThe folder this session runs in. Point it at an existing repository, or an empty directory for something new — the files stay yours, on your disk. — this control is not on the captured screen.

The buttons in this panel work — click them to look around.

1. Add a workspace

   Point Mirasim at the folder you want to build in — an existing repository, or an empty directory for something new. The host owns your project files, Git state and session history; most Mirasim state lives under ~/.mirasim, and per-project configuration under <workspace>/.mirasim.

2. Choose the agent

   Mirasim's built-in agent, Claude Code, or Codex. Existing Claude Code and Codex sign-ins carry over as-is. If an agent is not installed yet, Agent Config can install it for you.

3. Choose the model and reasoning level

   Each session carries its own model and effort. Native subscription models and your own model profiles both appear in the picker, grouped as Native and My Models.

4. Decide on isolation

   The composer can start the session in its own linked Git worktree, and lets you pick the base branch it starts from. Leave the worktree off for a single session; turn it on the moment you go parallel.

Run one real task#

Type a prompt and send it. Give the agent one small job with a finish line you can check in seconds — a test that should go green, a page that should render, a script that should run. The point of the first session is to feel the whole loop once: instruct, watch, review.

1. Describe the outcome, not the keystrokes

   “Add a /health endpoint that returns the current git sha and uptime” beats a line-by-line recipe. Agents do better work from a clear finish line than from micro-management.

2. Watch it work, and stay in the loop

   The transcript shows thinking, tool calls, tool results and sub-agent work as it happens, with a live usage line for the turn. You can queue the next prompt, steer the running turn, or stop it — none of which requires starting over.

3. Review before you keep anything

   Work lands as ordinary edits on the real repository. Open the Git panel, read the diff, run the result, then stage and commit what you want. Nothing is committed behind your back.

• ⌘KCommand palette — jump to any session, run any workbench command, search every transcript
• ⌘NNew session pane
• ⌘DSplit a new pane to the right
• ⇧⌘EOpen the files and Git surface for this pane's workspace

Prefer a terminal, an editor, or your phone?#

The desktop app is where the full workbench lives, but it is not the only door. Each surface talks to the same host, so a session started in one shows up in the others.

./mirasim doctor       # check the install and its environment
./mirasim              # Mirasim's built-in agent
./mirasim claude       # Claude Code, with its own TUI and auth
./mirasim ui-cli help  # the scriptable control surface