Basics

Sessions

A session is one agent working on one task in a project. Sessions run side by side, in every project, and each says when it needs you.

The sidebar

The sidebar lists your sessions in each workspace, the one you last worked in first, each with its project's name at its end. An open session's row says under its title what it waits on you for, what it does now, or the first line of its last reply. Where a session runs shows when you hover it, in the chip under its message box, and in its line while its machine is connecting, reconnecting or can't connect. Quiet sessions you haven't worked in for a week, and past ones, are behind Earlier at the end of their workspace (More shows older ones). A project whose folder is gone says so in a row of its own.

Right-click a session for its menu: its project's menu is in it (New session, New automation, New worktree…, Open terminal, Move to workspace, Copy path, Archive and Remove from sidebar). Drag a session onto a workspace to move its project there.

Archive puts a project away in Archived, at the bottom of the sidebar (also ⌘P, Archive …). Its sessions stop, as with Remove from sidebar, but it keeps the ones you had open: click it in Archived to bring it back with them, or right-click it for Unarchive.

To keep a session on top of the sidebar, whatever its project, right-click it and choose Pin to top, or press ⌘P and choose Pin session to top. A pin marks it while it's idle. Unpin takes it back to its workspace.

A session's own subagents show under it, on a line down from its mark: a spinner while one runs, with what it's doing now; a check once it's done; red if it failed; a grey ring if it was stopped. Click one to see it in its session. They're the ones since your last message; past five, those that finished fold into one line (click it to show them). Only Claude Code's show so far. With Swarm on, a lead's workers sit under it the same way. One whose session is open here has its own subagents under it; one that isn't (the worker on the lead's own machine runs without one) opens with a click. In Machines, workers stay with their machine.

The mark before a session says how it is:

A folded workspace shows its most pressing mark. The Factory gathers what needs you from every project and machine.

Workspaces

A workspace holds several projects and their sessions under one name, with a goal, a Context, machines, rules, spend and a log of its own: Workspaces has all of it. Projects you haven't put in one are in No Workspace, always last in the sidebar, and so are agents left running and automations whose project isn't in the sidebar. Each is a group in the sidebar: its tile and name, then its sessions. Click its name to fold it; folded, it shows what in it calls for you, and a workspace's name shows a dot when one of its machines needs you or its work waits at its cap. Click its tile, or the gear beside its name, for its page.

Hover it for New session (+ while it has no project) and ⋯ (also on right-click): New session, Add a project…, each of its projects' menus, then Open workspace, Rename…, Move up, Move down, New workspace… and Remove workspace, which leaves its projects in No Workspace. A workspace keeps its place and its projects when renamed; each is a file in ~/.magnum/workspaces.

No Workspace fills by itself: every folder your agents have sessions in (Claude Code, Codex, Pi, OpenCode, Copilot and Antigravity, whatever account they ran on) is listed there, on this Mac when Magnum starts and on each machine as it connects. Temporary folders, agents' own folders and worktrees aren't, nor folders in Desktop, Documents and Downloads until you open a project there. It lists by project: a row per project, the one worked in last first, its sessions under it when you click it (the latest past ones at once, More for older); + on its row starts a session there, ⋯ is its menu. Projects nobody worked in for 30 days are behind Earlier. Remove from sidebar takes a project off for good: it isn't listed again until you open it.

Drag a session or a project onto a workspace to put the project there, onto No Workspace to take it out, or onto Archived to archive it. A project's Move to workspace does the same, New workspace… included (also right-click the sidebar where there's no row, or ⌘P, New workspace…). Drag a workspace's name onto another to take its place.

Starting a session

A new session is always in a project, named by the first chip under its message box. ⌘N, /new and the New session button at the top of the sidebar start it in the project of the session you're looking at (with none showing, the project you worked in last); New session on a workspace, in its project you worked in last; New session in a project's menu, there. Until you send the first message, click the project chip to put it in another: your workspace's projects, the other workspaces', or Open folder…. After that the chip only says where the session is.

A workspace with no projects has + in place of New session: it adds a project to it. On a machine that's still connecting, the session starts as soon as it's connected. An untouched new session is reused. It runs on the project's agent with Settings' defaults (Agents and models).

Switching between sessions

Besides clicking one in the sidebar:

Finding in a session

⌘F opens a find bar over the session. Type, and the newest message holding it is lit and shown, with how many there are ("2 of 5"). ↩, ⌘G or ↑ goes to the next older one, ⇧↩ or ↓ the next newer, round the ends; Esc or ✕ closes it. It looks in what you and the agent said, notices and cards, not in tools' output.

Allowing from the keyboard

When the agent asks to use a tool, the request sits on top of the message box with Deny, Always allow (when it can be remembered; its tooltip says where) and Allow. ⌘↩ allows the oldest waiting request and ⌘⌫ denies it; "1 of 3" says more are waiting. The tool's card in the conversation has the same buttons and the diff. Questions and plans are answered in their own cards.

Permission modes

The mode picker under the message box sets how much the agent does without asking you. ⇧Tab steps through the first three:

Bypass permissions, Full access and Don't ask (OpenCode, Copilot, Antigravity) let the agent edit files and run commands without asking: you confirm once per session, and the picker turns red. Claude Code restarts the session on the same conversation to take Bypass permissions, so not while Claude works.

New sessions start in Manual (Claude Code), Auto (Codex), Ask (Pi) or Ask first (OpenCode, Copilot, Antigravity), unless the agent's page in Settings gives another.

Stopping a turn

Esc or ⌘. stops the turn, as does Stop at the right of the message box; Esc first closes an open list in the message box. Claude Code still runs messages you queued; Pi gives its queued messages back.

Rewinding to an earlier message

Hover a message you sent and click Rewind (or right-click it: Rewind…). Choose what goes back to before that message: the conversation (your message returns to the message box), the files the agent changed since, or both. Rewind works for Claude Code and Pi, not Codex, and not while the agent works.

Closing and reopening

⌘W, or ✕ on the session showing in the sidebar, closes it: its agent stops, and the conversation stays among the project's past sessions. While it works or waits for you, Magnum asks first. ⇧⌘T reopens the session closed last; again, the one before. A past session reopens with a click and goes on when you send it a message.

Quitting Magnum doesn't stop a session that has started working: it keeps going, and Magnum picks it up when it opens again.

Titles and the session menu

A session is named by the first line of your first message, until Claude Code or Pi titles it after its first turn, or Copilot or Antigravity as it runs. Codex sessions keep their first message.

Click the title in the toolbar (with tabs, right-click the session's tab), or right-click a session in the sidebar, for its menu: Detach (or Dock), Continue on another copy of the project (Environments), Copy session ID and Close. Pi's sessions add their own, among them Session tree, Fork from a message… and Rename session…

Tabs and tiles

The sessions you open in the window line up as tabs in the toolbar, on the line with Run and the panes' buttons, from any project (another project's name shows beside its title), with the projects' terminals. Click a tab to show it. Point at a tab for its two buttons: Detach on the left, and ✕ on the right, which takes it off the strip (the session stays open in the sidebar; a terminal ends).

Detach (on a tab, the button at the right under the message box, the session menu, or ⌘P) turns every tab into a tile, side by side, then in rows, that session with the keyboard; the strip goes. Tiles are plain panes with a hairline between them: no frame, no title row. The one with the keyboard is lit, the others a shade darker; rest the pointer in one and it takes the keyboard (a click does too). From then on each session you open (from the sidebar, ⌘N or the Factory) joins the tiles. When there's no room for another, the tile you used least recently gives way; it stays open in the sidebar. Under a tile's message box, the environment and the pickers show their icons alone; point at one for its name.

Move the pointer to a tile's top edge and its strip shows: its title, Dock and ✕. Dock (the arrow there, the session menu, or ⌘P) turns every tile back into a tab, that session in front. The ✕ (or ⌘W in the tile) closes the tile: the session stays a tab, and nothing stops; closing the last tile docks it.

⌃⌥T switches between tabs and tiles. In tiles, ⌃⌥←, ⌃⌥→, ⌃⌥↑ and ⌃⌥↓ move to the tile beside (⌃⌥→ from the rightmost, and from a session in tabs, to the side pane when it shows Now or a file; ⌃⌥← back), and ⌃⌥↩ zooms the tile you're in to the whole area and back. Tabs, tiles and the strip come back after a restart; terminals don't (their shells end with Magnum). The window has every part of the layout, with its keys.

Density

Comfortable, Compact or Dense sets how much of the conversation fits: Settings → Appearance → Density, ⌘P → Density, or ⇧⌘L. Dense uses the pane's whole width, with smaller text. At Comfortable and Compact the conversation is a column in the middle of the pane: drag either of its edges to make it wider or narrower (480 to 1600 points), for every session; each density keeps its own width.