Core concepts
Host, workspace, session, pane, group — the small vocabulary that makes every other chapter obvious.
The loop: build, evaluate, evolve#
Mirasim is a local-first, multi-agent build space organized around one loop rather than a feature list. Agents build; simulated users try the result; the evidence decides what happens next. Everything in the product exists to make one turn of that loop fast, and to start the next turn from what the last one learned.
- Build — several agents at once in split panes and workspace groups, each session in the same project or its own linked worktree, with files, diffs, terminals, Git and artifacts open beside the agent that produced them.
- Evaluate — the opt-in $eval skill sends simulated users through the real browser, phone, shell or rendered artifact, and treats runtime actions and observations as the evidence. Reading the source is not user evidence.
- Evolve — behavioral traces become feedback and the next tasks. Keep a change, revert it, or re-verify it with held-out cases.
The host owns the truth#
One `mirasim serve` instance owns one SessionHost, and that host owns everything real: project files, Git worktrees, session history, artifacts, recordings, schedules and local usage data. Every surface is a client of a host — not a copy of one.
Normally your Mac is the host: the desktop app supervises a local server and talks to it. The desktop can instead point at a self-hosted macOS or Linux server (there is no Linux GUI release). The VS Code extension embeds its own host. Ordinary `mirasim`, `mirasim claude` and `mirasim codex` commands launch an agent directly.
A workspace is a folder you added#
The sidebar is not a view onto something else — it is the list itself. A workspace appears there because you added that folder, and every one of them can be removed, so a fresh install opens on an empty sidebar and an "Add a workspace" prompt rather than on some folder you never chose.
One exception keeps the list honest: if a session starts in a folder that is not on the list yet, the host adds that folder for you. A folder that owns sessions is therefore always a real, removable workspace — the sidebar never shows a row you cannot act on, and never hides sessions that exist.
A session is one conversation with one agent#
A session pairs one agent with one model and one reasoning level, running in one workspace folder — optionally in its own Git worktree, optionally starting from a base branch you choose. It keeps its own transcript, its own prompt queue, its own todos and its own terminals.
Because agent, model and tool are configured independently, the model behind a session can be a different one from the model behind the session beside it: a strong reasoning model for the design pass, a cheaper fast one for the mechanical follow-through, a local model for anything that must not leave the machine.
- Agent
- Mirasim's built-in agent, Claude Code, or Codex. Chosen per session; the active account for an agent is agent-wide.
- Model + effort
- Picked per session from native subscription models and your own profiles. A queued prompt keeps whatever was selected when you sent it.
- Workspace + branch
- The folder it runs in, and the base branch it starts from.
- Worktree
- Optional isolation: a real linked Git worktree on its own branch, created by the agent and tracked by Mirasim.
- Transcript
- Turns, thinking, tool calls, sub-agent work, plans, decisions — searchable, forkable, exportable.
Groups, tiles, document stacks#
The workbench has three nesting levels, and each one solves what the level below cannot. Learn them once and the layout stops surprising you — because every surprise in a multi-pane tool is the same surprise: something you were watching disappeared.
Group stripWhole scenes live up here. Switching one never tears down what is running inside the others. — this control is not on the captured screen.
The buttons in this panel work — click them to look around.
- GroupA whole scene, switched from the strip in the title bar
Each group holds its own layout. Nothing is torn down when you switch. A session can appear in as many groups as you like, and closing a group closes the view only — its sessions keep running.
- TileOne box in the split tree: a session, a terminal, or a document
Splits behave like a terminal multiplexer's. Minimum sizes are measured in pixels against the live stage, so density follows your display rather than a fixed fraction of the window.
- Document stackTabs, but only inside a document tile
Documents stack; sessions and terminals never do. That asymmetry is the safety property: a file can be pushed behind a tab, a running session cannot.
Artifacts, evidence and traceability#
Everything a run produces — builds, screenshots, logs, exports, evaluation reports — stays anchored to the host that produced it, previewable beside the session that made it. Deliveries an agent hands back are listed as artifacts you can open, reveal in the file system, or download.
That anchoring is what makes the loop honest. A conclusion you cannot trace back to a run is treated as no conclusion: evaluation preserves screenshots, commands, traces and artifacts, and keeps what was observed separate from what was inferred.
Where things live on disk#
- ~/.mirasim
- Host state: settings (setting.json), session records, raw recordings, the local usage ledger, agent status files.
- <workspace>/.mirasim
- Project-scoped configuration that belongs in your repo — workspace skills, schedules.json.
- ~/.apodex
- The underlying agent runtime's own state. Mirasim is the entry layer; apodex is the agent and relay beneath it.
Something wrong or missing on this page? Tell us