Basics
Workspaces
A workspace is a kind of work with a goal: its projects, what its agents should know, the machines its work runs on, its rules, what it spends and what was done in it. Everything a workspace holds reaches every agent working in its projects, on any of its machines, with Magnum open or closed.
┌──────────────────────────────┐
│ Client Work │
│ "Deliver client work, │
│ kept apart." │
└──────────────┬───────────────┘
┌──────────────┬───────────────┼───────────────┬──────────────┐
┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│ Context │ │Projects │ │Machines │ │ Policy │ │ Spend · │
│ files, │ │ folders │ │ ready │ │ Strict, │ │ Audit │
│ notes │ │ & repos │ │ & in │ │ rules │ │ cap, │
│ │ │ │ │ sync │ │ │ │ the log │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
└──────────────┴───────────────┼───────────────┴──────────────┘
▼
every session, worker and automation in its projects
Magnum starts you with four empty workspaces, each for a kind of work with a goal of its own: Product ("Ship what customers use."), Client Work ("Deliver client work, kept apart."), Open Source ("Maintain public code.") and Lab ("Try ideas cheaply."). Keep, rename or remove them; one you remove doesn't come back by itself, and New workspace… offers the ones you don't have under its name field (typing one's name makes it too). Projects you haven't put in one are in No Workspace, which keeps your own settings and none of what follows.
Open a workspace's page from its tile or the gear beside its name in the sidebar (or ⋯, Open workspace; ⌘P, Open workspace …). It opens in a tab.
Goal
Write what the workspace's work is for, in your own words; it's kept as you type. Every agent working in its projects is told it: a new session from its start, one already going with your next message, and again when you change it; workers and automations too. A workspace with no goal says nothing.
Context
What you keep with the workspace for every agent in it: specs, docs, decisions, screenshots. Drop files, folders or images on the page (or +), or write a note there; each is copied into the workspace, on this computer, and nothing is sent anywhere. A folder brings its files (not hidden ones, nor what tools make, like node_modules); a file that looks like it holds a secret (.env, a key) is asked about first. Click an item to open it (a note, to write it again); ⋯ or right-click for Open, Reveal in Finder, Rename…, Caption…, Replace… and Remove.
you ── drop · write a note ──▶ Context ◀── context_search ── agents
(passages, context_read
words + context_list
meaning)
Sessions in the workspace's projects get three tools for it, with no question asked: context_search (the passages that answer best, with their files), context_read and context_list; they're told the Context is there once it holds something. Workers and automations' sessions get them too, and so do sessions on the workspace's machines. Text, code, HTML, PDF and Word files are read, and on a Mac the text in an image (a screenshot, a diagram, a photo of a whiteboard); an image with no text, or another kind of file, is found by its name and your caption.
Search goes by the words a passage shares with the question and by meaning: a small model that ships inside Magnum (about 30 MB, nothing to download, nothing sent anywhere) reads each passage as it's added, so a question in other words than the text's still finds it. The model is a small one: it helps with other wordings, and misses some.
Projects and repositories
The page lists its projects, with where each one's copies are. + opens a folder on this computer, clones a repository by its address (owner/name from GitHub, or any address git clones), or clones one of your GitHub repositories (From GitHub, when GitHub's tool is signed in on your computer).
A workspace keeps its projects' repositories, so a computer knows a project by what it is rather than by a folder. One this computer has no copy of is listed with Clone (it goes in ~/<name>), one only on the workspace's machines with Clone Here. A private repository that needs GitHub's sign-in offers Sign In to GitHub on its row, then clones. A project with no remote stays this computer's alone, and its row says so. Worktrees show as how many a project has.
The skills and connectors the projects bring (kept in the project: .claude/skills and .mcp.json) are listed under them.
Machines
Where the workspace's work may run besides your own computer. + adds one of your machines (or a new one), and Magnum gets it ready once:
+ magnum-orb
│
▼
connect ················ its node installed or updated
│
▼
copy each project ······ one with no copy there: cloned
│ from its repository
▼
agents and sign-ins ···· asked once, under the machine
│
▼
copy the workspace ····· goal, Context, search model
│
▼
Ready ◀──────────┐
│ │
└───────────┘ kept in sync: new projects,
Context and goal changes
What needs you there (installing an agent, signing Claude Code in, who commits: asked once for all its projects) is asked under the machine, and the workspace's name in the sidebar shows a dot until it's answered. The row then says Ready and what the copies take there. After that it's kept so: a project added to the workspace is copied there, a Context or goal change follows within seconds, and a machine that was away catches up when it connects.
Swarm in the workspace starts each lead with its machines ticked (those in your list of machines), already ready; untick one for that lead. The environment chip lists them first. A machine can be in several workspaces; each keeps its own files there, apart from a Magnum of that machine's own. A machine is known by its node's key too, so another at its address isn't taken for it; one a teammate added that isn't in your list says so, with Add to My Machines (you reach it with your own access).
⋯, Remove from Workspace takes it out: the workspace's files there go (when it next connects, if it's away); its copies of the projects stay (they may hold work not pushed), as does anything running there.
Policy
How work goes in the workspace: every session, worker and automation in its projects, on any of its machines, Magnum open or closed. Pick a preset; each rule under it can be changed on its own (its row says "changed from" the preset, and its menu takes it back).
| Open | Guarded | Strict | |
|---|---|---|---|
| Sessions start | the agent's default | asking before changes | asking before changes |
| The most a session may do | anything | run what it judges safe | edit without asking |
| Workers edit without asking | on | on | off |
| The lead allows its workers' commands | on | on | off |
| Pushes and pull requests | agents may | you do | you do |
| A worker's work lands | when its check passes | when its check passes | when you land it |
| Each session in its own worktree | workers only | on the workspace's machines | everywhere |
Product and Open Source start Guarded, Client Work Strict, Lab Open.
- The most a session may do: the mode picker and Shift+Tab go no further, an open session past a lowered limit comes down to it, and automations' steps too.
- The lead allows its workers' commands off: you answer them, and with Magnum closed they wait for you.
- Pushes and pull requests by you: Claude Code can't push or open, merge or ready a pull request; you push with Ship or the git panel, and an automation's open-PR step waits for your Open It. The other agents still ask before commands while they're asking.
- Each session in its own worktree: a new session starts in a fresh worktree of its project, with what the repository lists for worktrees and its setup if you allowed it; one you leave untouched goes with its worktree. An automation's step meant for the project's folder gets one too.
The Swarm panel's two switches are the workspace's rules.
Where its agents run
These rules are the workspace's own, whatever the preset:
- Claude Code runs on any account, or one organization's (of your Claude accounts; known by its id, not its name).
- Codex runs in any ChatGPT workspace, or one (of those its sessions ran in).
- OpenCode and Pi use any provider, or those you tick.
- Agents: all, or those you tick. Copilot and Antigravity are kept out this way: they don't say which organization they run in.
send
│
▼
this agent used here? ──── no ──▶ refused, with why
│ yes (what you typed stays;
▼ switch agent or account
its account in the under the message box)
workspace's organization? ─ no ──▶ refused, with why
│ yes
▼
the turn starts
The agent picker offers the workspace's agents, and leads pick workers from them only. Each member signs in as themselves in that organization; nobody shares a sign-in. A Strict workspace asks once, at its first session, whether to keep it on the organization (or ChatGPT workspace) that session runs on.
Every change of rule is in the Audit.
Spend and the cap
What the workspace's sessions cost, from the day this Magnum counts it. First the plans its turns ran on, with their 5-hour and weekly windows: those are the limit, and they're the whole account's, shared with your other work. Then This week (from Monday) or This month: At API prices for turns on a plan (what they'd cost on a key, not what you pay), Spent for turns paid per use (a key, a plan's extra usage); the last 30 days by day; and By project and By agent when there are several.
A worktree's turns are its project's. Every agent's turns count while Magnum shows the session; Claude Code's count with Magnum closed too (workers, automations, sessions left running) on this computer. A turn seen twice counts once. Claude Code sent to another provider isn't counted, nor agents that report no cost (Copilot, Antigravity).
The Cap is what the workspace's work may spend a week or a month, at API prices (Lab starts at $25 a week; the others with none):
$0 ─────────────────────── 80% ──────────── cap ───────────▶
work goes on Magnum work Magnum starts waits:
says so workers a lead asks for,
automations on their schedule
(Run It · Stop here)
Nothing running is stopped, and your own messages and Run now never wait. Raise the cap from its menu, or Let Work Go On Until It Resets; the workspace's name shows a dot while work waits. The cap counts what this computer counted.
Audit
The workspace's log, newest first: who did what (you, an agent, a lead, the chief, an automation or Magnum), in which project and session, on which machine, and what a turn cost. It keeps the messages you send and the turns they start, what agents ask and who answered, workers started, landed, failed or stopped, reviews, automations' runs and their steps, and changes to the workspace itself (its name, goal, projects, machines and rules) and to its Context. Type in Filter to keep the rows with those words; Export saves the whole log as a spreadsheet's file (CSV) and opens it. The log stays on this computer and is never cleared.