Troubleshooting & FAQ

Frequently asked questions#

Common issues#

1. The app will not open after downloading

   macOS asks you to confirm opening an app from the internet on first launch — right-click the app and choose Open once. If the download looks damaged, re-download and check it against SHA256SUMS before opening it.

2. An agent cannot find git, gh or docker

   An app launched from the Dock does not inherit a terminal's shell environment. Check Extensions → CLI tools: it lists what is on PATH and whether each is signed in, which usually turns “the agent could not push” into “gh was never authenticated”.

3. A session went quiet

   The session says why: quiet for N seconds, a named tool still running, awaiting the model, or the process merely alive. A stalled session resumes when you send a message. If it is going in circles rather than stalling, that is almost always an underspecified goal — interrupt it and restate the finish line.

4. Screenshots or screen analysis do not work

   On macOS these need Screen Recording, and reaching Desktop or Downloads needs Full Disk Access. Grant them to the app that launched Mirasim — Permissions walks each one and re-checks on demand, because macOS offers no prompt at all for some of them.

5. A Git operation refused to run

   The panel names which ordinary Git situation you are in — local changes would be overwritten, diverged branches, no upstream, the remote is ahead, an unfinished merge, refused credentials — and offers the move that resolves it, such as stash-and-pull or pull-with-rebase. Nothing has moved when you see that message.

6. Two sessions produced conflicting changes

   If they ran in worktrees, nothing is lost: merge the better one, then rebase or regenerate the other against it. Next time, give parallel sessions non-overlapping slices — or run them deliberately as competing drafts and keep one.

7. A worktree will not delete

   Git refuses to remove a worktree that has uncommitted changes. Commit or discard them, then delete the session and its worktree together.

8. Quota ran out mid-task

   Switch the active account, or sign in to the relay and set a fallback threshold so the next long task does not stop at the same place. A turn that routed through the fallback is labelled in the transcript, so you can tell what happened after the fact.

9. A file I had open changed underneath me

   That is usually an agent writing it. The editor says so and asks whether to reload from disk or keep your version — it never discards either silently. Save or close an edited file before restoring its Git changes.

10. ui-cli cannot reach the app

    Point it at a running instance: --port 4970 for the installed app, --port 4950 for a development desktop instance, or run without --port to spin up a private throwaway server for that one command.

11. An MCP server's tools never show up

    Run its health probe — a server that fails its handshake produces an agent that quietly cannot do what you asked. For connectors, validate records the tool count or the error, and re-running the OAuth grant fixes an expired token.

12. A schedule did not run

    Schedules fire on that host's clock while Mirasim is running, and missed fires are skipped rather than replayed in a burst. The minimum interval is 10 minutes. Check the schedule's run history, and use Run now to test it without waiting.

Getting help#

Questions, bug reports and evaluation deep-dives all reach a human at the contact address in the footer. Include the workspace, what you asked the agent to do, and what it did instead — and where you can, export the single round that went wrong. A preserved trace beats a description every time.