Quickstart

Install Mirasim

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

1. Download the DMG

   Get Mirasim from the Download page. macOS needs an Apple Silicon (M-series) Mac on macOS 13 Ventura or later; Linux ships as an AppImage or a .deb, x64 or Arm64, for Ubuntu 22.04 or an equivalent glibc distribution; Windows needs Windows 10 1809 or later. The Windows installer is not code-signed yet, so SmartScreen warns on the first install — check the file against SHA256SUMS and keep going. The page only ever hands you a build for the machine you are on, never another platform's file.

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

Default

42%

8%Cloud

2

checkout-api

Fix the two-pane split on narrow screens23h

Wire the export button to the render queue1d

Cache the product list between routes3d

Make the empty state explain what to do next3d

Retry failed uploads instead of dropping them3d

+ 5 more

design-system

Move the settings page behind a feature flag<1m

Give the search box a keyboard-only path26m

Stop the sidebar from scrolling with the page3d

Trim the bundle by lazy-loading the editor9d

Handle the expired-token case on refresh9d

+ 87 more

docs-site

Log slow queries with their bind parameters2d

Split the checkout form into two steps18d

infra

Round prices at display time, not in storage3d

Redraw the chart only when data changes3d

Name the exported file after the report4d

Warn before leaving a half-written draft9d

Keep the diff view in sync while typing10d

+ 13 more

mobile-app

Make the date picker respect the locale2d

Batch the write queue instead of one call each7d

Show which filters are active, not just the count8d

Fall back to the cached list when the API is down8d

Let the table remember its sort between visits9d

+ 2 more

storefront

Add dark mode toggle to settings3d

Explain the error instead of printing the code8d

Fix the two-pane split on narrow screens8d

Wire the export button to the render queue8d

Add dark mode toggle to settings8d

infra

Cache the product list between routes21h

Make the empty state explain what to do next2d

Retry failed uploads instead of dropping them2d

Move the settings page behind a feature flag3d

Give the search box a keyboard-only path4d

+ 9 more

payments

Stop the sidebar from scrolling with the page9m

Trim the bundle by lazy-loading the editor25m

Handle the expired-token case on refresh3h

Log slow queries with their bind parameters4h

Split the checkout form into two steps20h

+ 47 more

Add Workspace

YYou

storefront/New Session

Type a prompt — paste or drop files too

~/code/storefront

Open TUIOpen Terminal

storefront

Claude/kimi-k3

max

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