Mirasim Documentation
Core concepts
What a host, workspace, session, pane and group are.
Three layers: workbench, team, cloud
Mirasim has three layers:
- Workbench (local, free): the desktop app. Run several agents at once in split panes and groups, each session in the project folder or its own worktree, with files, diffs, terminals, Git and artifacts beside it. Following sessions from the phone app is included.
- Team: channels, threads, comments and notes on artifacts, with each turn showing who sent it. Available in team spaces, on computers attached to the cloud and on shared accounts, at no separate charge (chapters 11 and 12).
- Cloud (paid): team spaces on Linux or Mac that keep running when your laptop is closed. Each space has 5 collaborator seats (more can be added) and room for 100 observers; the team can share space credit and its own API keys (chapter 11). Team spaces are not yet available in mainland China, Hong Kong or Macau (chapter 10).
The host: where sessions run
The host is where your agents run and where project files, Git worktrees, session history, artifacts and schedules are kept. Normally it is your own computer, started by the desktop app. The desktop app can instead connect to a macOS or Linux server you run yourself. A team space, or a computer attached to the cloud, is also a host (chapters 10 and 12). In the app each host is a space; switch between them from the space menu at the top of the left column.
A workspace is a folder you added
The sidebar lists the folders you added as workspaces, and each one can be removed. A fresh install starts with an empty sidebar and an Add workspace button. If a session starts in a folder that is not on the list yet, that folder is added automatically.
A session is one conversation with one agent
A session is one agent with one model and one reasoning level, running in a workspace folder, or in its own Git worktree based on a branch you choose. Each session has its own transcript, prompt queue and terminals.
- Agent
- Claude Code, Codex or another installed agent, chosen per session. Which account an agent uses applies to all of that agent's sessions.
- 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: the session runs in a Git worktree on its own branch.
- Transcript
- Turns, thinking, tool calls, sub-agent work, plans, decisions — searchable, forkable, exportable.
Groups, tiles, document stacks
The workbench nests three levels: groups, tiles and document stacks.
- GroupA whole scene, switched from the group strip above the panes
Each group keeps its own layout. A session can appear in several groups; closing a group closes only the view, and its sessions keep running.
- TileOne box in the split tree: a session, a terminal, or a document
- Document stackTabs, but only inside a document tile
Only documents stack into tabs; sessions and terminals always keep a tile of their own.
Artifacts
Builds, screenshots, logs, exports and evaluation reports stay on the host that produced them and can be previewed beside the session that made them. Files an agent delivers are listed as artifacts you can open, reveal in the file system, or download.
Where things live on disk
- ~/.mirasim
- Host state: settings (setting.json), session records and local usage data.
- <workspace>/.mirasim
- Project configuration that can be committed with your repository: workspace skills and schedules.json.
Something wrong or missing on this page? Tell us