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.

The setup assistant on first launch

The first launch opens a setup assistant before the workbench. Signing in is required and there is no Skip. Back works on every step after the first.

1. Sign in

   Use GitHub or Google, or a code sent to your email, and agree to the Terms and the Privacy Policy. Once you are signed in, this step shows your plan, and you can redeem a code here.

2. Install an agent

   Install Claude Code or Codex; one is enough. The assistant lists what this computer already has and installs what is missing. You can continue while it installs.

3. Skills & plugins

   The skills, plugins and MCP servers already on this computer carry over as they are, and you can turn on Computer Use here. Change any of it later on the Plugins tab in Settings.

4. Get started

   Opens the workbench.

With a plan, agents run on the platform and use the plan's credit. On the free plan, agents run on their own accounts (Own). You can switch this later in Settings.

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