Many agents

Balanced

With Balanced on, a session leads: it hands pieces of its task to workers on the machines you tick. Each worker works in a worktree and a branch of its own, and what passes the repository's check lands back in the lead's branch.

Turning it on

In a session, open the environment menu (the chip under the message box) and choose Balanced, or press ⌘P and choose Balanced…. The session restarts on the same conversation as a lead, with Magnum's tools for starting workers, and Balanced's panel opens above the chip.

Ticking machines

The panel lists this Mac, the machines you added, and the hosts in ~/.ssh/config you haven't added yet. Tick the ones its workers may use. The first time only this Mac is ticked; after that your ticks are kept for the project.

For each machine you tick, Magnum connects to it (installing or updating its node), copies the project to ~/<repository> when there's no copy yet, and checks that it has room and that git knows who commits there. It asks only what's yours to decide, under the machine: installing the lead's agent there (Claude Code, Codex, or Pi, which needs Node.js 22.19 or newer there), installing git there (with its package manager, where sudo asks no password), stopping an agent left running that holds the room, committing there as you. Leave out unticks the machine. A machine where Claude Code isn't signed in says so: sign in there, or give Magnum this Mac's sign-in for your machines (Settings → Accounts), then Try again. When the project runs on an account you added, it's that account Magnum looks for there, after copying the project: Sign in, under the machine, opens a session there whose card signs it in.

The project's own commands are asked once too: its worktree setup (what readies a new copy, such as installing its packages: see Changes and worktrees) and its check of workers' work. Allow them, or Not now for this run. The check is a command the project names in .magnum/settings.toml, under [worktree], such as check = "npm test".

Under the machines, the switch Workers edit without asking lets workers change files in their worktrees without asking first, whatever their lead asks before. Their commands still go by the lead's permission mode. Under it, the switch The lead allows its workers' commands sends what a worker asks to run (anything but an edit) to its lead instead of you.

While machines get ready

Closing the panel stops nothing: click outside it or press Escape. The chip shows a spinner while machines get ready, a dot when one needs you, and +2 for two more machines ticked. Once they're all ready, the session says so ("Balanced: ready on 3 machines"). The chip opens the panel again.

Starting workers

Ask the lead in plain words: split the work across your machines, or start one worker on a machine for one piece. The lead starts each worker with its task. A worker starts from the lead's latest commit, in the lead's permission mode (on another agent, the mode that goes as far and no further: Accept edits becomes Codex's Auto); the lead hears when it has uncommitted changes a worker won't get. A worker meant for a machine still getting ready waits for it.

When the lead plans the work, the plan shows above its message box, each piece with where it runs and why; the lead starts it, or you can start it there yourself. The pieces that don't depend on each other run at the same time; a piece that builds on another waits until that one has landed in the lead's branch, then starts on its own, and the lead hears so. Among machines equally free, a piece goes where the project's setup has already run.

The lead's session lists its workers above the message box: a dot for how each is doing (a ring: finished, not landed; filled green: landed), a click opens it. Past five, those that are done (landed, stopped, or retried as another) fold into one line, such as "14 landed · 3 stopped · 1 retried"; click it to show them, again to fold them. Magnum keeps that for each lead.

Each worker is a session of its own. Its first message is its piece; what a worker is and does (stay on its branch, commit, sum up, the repository's check, its budget) is in its agent's own instructions, given again after its context is compacted (summed up to make room). It shows under its lead in the sidebar (Sessions), and beside its lead on the Board.

Workers ask their lead first

A worker's question or plan goes to its lead as a message from Magnum, not to you; with The lead allows its workers' commands on, so does a command it asks to run. The lead answers it (the worker's agent hears it as the answer it waited for), or passes it to you when it's your call. With the chief running, what the lead passes on goes to the chief first. A lead whose agent isn't running, or hasn't the tools to answer yet (one started before Magnum was updated, until it starts again; one on a machine whose node is older than this Magnum), or that doesn't answer in 10 minutes, leaves it to you, as any session's ask. You can still answer in the worker's session meanwhile (its card says Asked its lead): the first answer counts. On the Board, the worker asks its lead under Running, and once its lead has answered, its row says so ("Allowed by its lead").

Reviews and ideas

When your task is done and combined in its branch, the lead puts it to you: a row in Board › Now's queue with what it says it did, what would ship, the repository's check run again on its branch, and the screenshots or clips it made. Ship starts Ship for the project (the push still waits for you); Correct… sends the lead a line of yours, and it puts the work to you again once fixed; Not now leaves it. A lead's idea beyond your task comes the same way, instead of into the work: Go ahead tells the lead.

Budgets

Give the lead a budget in your message, as in "budget $2": its plan splits it among the pieces by size, and each worker is told its share. A worker that reaches its budget stops; it isn't tried again, though what it finished still lands if it passed its check. A worker on Codex or Pi stops its turn once its budget is spent, as Claude Code does on its own; Codex's spend is reckoned from its tokens at its model's list prices.

Codex's sandbox keeps a worktree's git folder from it, so a Codex worker asks to stage and commit: Magnum allows that for it (only git add and git commit in its worktree), and asks you nothing.

Checking and landing

When a worker finishes (a turn that ends while its own subagents still run isn't the end: it picks up again with their reports), Magnum checks its branch: its commits, nothing left uncommitted, and the repository's check when the project has one (check under [worktree] in .magnum/settings.toml). The lead hears what it found, and how many subagents the worker ran and how many of them failed.

A worker whose check passed lands on its own in the lead's copy, once that copy has nothing uncommitted, and the lead hears how it landed. That holds when its budget ran out on the turn that finished the work; it takes no more turns after. Without a check, Land on the Board lands a finished worker.

A worker that fails is tried again, three attempts in all: after a pause, with its agent restarted, on another ticked machine, or on a stronger model, depending on what went wrong. What's yours to fix, such as signing in or a budget, isn't tried again.

Plan limits and the reserve

On a subscription, what runs out is the plan's usage windows (the 5-hour one, the weekly one), shared by every session signed in to that account on every machine. Magnum keeps each account's windows as its sessions report them, so it knows a machine's limit even with no session open there.

A worker whose plan refuses it for its limit pauses until the limit resets and goes on by itself: the lead hears "Magnum pauses it until the limit resets at 14:00" (it goes on a minute after), and the Board shows it as paused, with the time it goes on under Next. A pause isn't one of its three attempts. Only when the reset is more than 30 minutes away, and another agent has room, does the piece move to that agent instead. A lead refused for its limit is told to carry on once it resets.

Plan reserve, in Balanced's panel, keeps part of each window for you: Off, 10%, 20%, 30% or 50%. An account with less than that share of a window left takes no new workers; neither does one that's refused or on extra usage (paid). The lead hears why ("its plan's 5-hour window is 84% used, past the 20% you keep, resets 14:00"), and a machine whose plan has more room wins among those equally busy. Workers already running aren't stopped.

With Magnum closed

Each machine's node (the small program Magnum installs there) includes Magnum's engine, which runs a lead's Claude Code workers on the lead's own machine without Magnum: it starts them, answers what they ask by their lead, checks and lands their branches, tries them again there (after a pause, restarted, or on a stronger model; never on another machine or agent), and tells the lead. With Magnum closed, it does that when you ticked the lead's own machine. With Magnum open, only when that's the only machine ticked; otherwise Magnum places the work across your machines.

What needs Magnum itself (a worker on another machine, a picture of a page) is kept by the node until Magnum opens: the lead hears "Magnum isn't open: it keeps this start_worker call and runs it once it opens", and Magnum runs it as it connects, telling the lead how it went. Magnum Helper's menu says how many calls wait.

The Board shows the engine's workers as e1, e2 (and e3@build-box for another machine's), beside Magnum's own: Stop, Land and Dismiss reach the engine that runs them.

Schedules

A lead can be told something on a schedule, Magnum open or not: ask it ("every weekday at 7, sum up what landed overnight"), and it schedules it. Times are the lead's machine's: daily 09:00, weekdays 18:30, every 30 minutes, every 2 hours (5 minutes at the least), or once 2026-11-12 09:00. When one is due, the lead gets "[Magnum] Scheduled (s3, weekdays 07:00): …" (s3 is the schedule's name, for removing it) within half a minute. Balanced's panel lists the lead's schedules with Remove; on the Board, the next one shows under Next.

See Balanced in practice for whole runs, start to finish, and The chief for one session over every lead.

Turning it off

Turn off the switch in Balanced's panel, or press ⌘P and choose Turn Balanced off.