Quickstart

Install Mirasim

Mirasim is a desktop app for macOS, Linux and Windows. Get the installer for your computer from the Download page.

1. Download the installer

   macOS needs macOS 13 Ventura or later. Choose the Apple Silicon installer for an M-series Mac, or the Intel (x86_64) installer for an Intel Mac. 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; if SmartScreen shows a prompt on the first install, confirm it to continue.

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.

3. Verify the file (optional)

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

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

Click the account card at the bottom left, then Version: it shows the version you are running, when it last checked, and whether a new version is ready. New versions download on their own; click once to install. Help is on the same page, with the documentation and Send feedback. Feedback can be sent anonymously, but anonymous feedback cannot be answered.

First launch and Get started

The first launch asks two things: sign in, then where you will work. Installing agents and choosing credit happen in the window, on Get started.

1. Sign in

   Use GitHub or Google, or a code sent to your email, and agree to the Terms and the Privacy Policy. Signing in is required and there is no Skip. Once you are in, the next step opens by itself.

2. Choose a space

   Your spaces lists the spaces this account can enter; press Enter on one. You can also create a cloud space, or paste an invite link a colleague sent you. To work on this computer, choose This computer.

3. Get started

   On this computer, the window opens with Get started. Set up an agent and credit there, then press Start a session.

Get started opens by itself only the first time. To come back to it, press ⌘K and search “Get started”, or switch credit on the space's Credit page.

Add a workspace and pick an agent

1. Add a workspace

   Click Add workspace in the sidebar and choose a folder: an existing repository, or an empty directory.

2. Choose the agent

   Claude Code, Codex or another installed agent. Existing sign-ins carry over. To install an agent, use Agent config.

3. Choose the model and reasoning level

   Each session has its own model and effort. The picker groups models as Native and Your models.

4. Decide on isolation

   Turn on worktree in the composer to run the session in a new Git worktree, based on the branch you pick.

Run one real task

1. Send a prompt

   Describe the result you want in the prompt box and send it.

2. Watch and steer

   The transcript shows thinking, tool calls and results, and sub-agent work as they happen, with the usage for the turn. While it runs you can queue the next prompt, steer the current turn, or stop it.

3. Review and commit

   Changes are made in the repository itself. Open Git on the right toolbar to read the diff, then stage and commit what you want to keep.

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

Other ways to use Mirasim

Every surface connects to the same host, so a session started in one shows up in the others.

~/.mirasim/bin/mirasim doctor       # check the install and its environment
~/.mirasim/bin/mirasim claude       # Claude Code, with its own TUI and auth
~/.mirasim/bin/mirasim codex        # Codex, with its own TUI and auth
~/.mirasim/bin/mirasim ui-cli help  # the scriptable control surface