Shipping

Run and Ship

Run starts the project you're working on and shows it: a web app in a browser tab, a phone app on a simulator or emulator in a device tab. Ship takes your work to its origin: it commits, tests and pushes, asks you before the push, and follows what happens after.

Running the project

Click ▶ in the toolbar, or press ⌘R. The command runs on the project's machine, in a terminal tab in place of the session, named ▶ and the target's name. Press ⌘R again to restart it. While it runs, the button is ■ (Stop): the program gets Ctrl-C, and is ended if it's still running a few seconds later. ⌘P has Run and Stop too, and on a Mac so does the Project menu.

Choosing the command

Magnum takes the first of these it finds:

• the repository's .magnum/settings.toml: a [run] table with command, and optionally name, kind (web, ios, android, desktop or cli), url and cwd; [[run]] for several;
• what Magnum found, or you typed, for this project before;
• the project's own files: package.json scripts, Cargo, Tauri, Trunk, Django, Rails, Go, Flutter, Xcode, Gradle, a Procfile, docker compose, a Makefile;
• Claude Code's Haiku reading the repository, without changing anything, on a budget of 10 cents.

When nothing is found, Magnum asks you. Right-click Run for its menu: an item for each target (Run Web, say), Open and the address while it serves, Edit run command… and Find again. Edit run command… asks for the command, keeps it for the project and runs it; for a target the repository's [run] names, your command is kept in Magnum (the repository's file isn't touched) and runs in its place. Find again forgets what was found and what you edited, and looks again. ⌘R runs the target you ran last.

Previewing a web app

When the program prints a local address, a browser tab opens in the session's place on a Mac (in tiles, a tile), with Back, Forward, Reload, the address and Open in browser; the next run loads its address in the same tab; another address the program prints later opens in a tab of its own. It tiles like any tab, and you can open more with + → New browser (The window). On Linux the address opens in your browser. For a project on another machine, its port is forwarded over the SSH connection first.

Phones

Phone apps run for projects on your own computer, not on other machines. For iOS, on a Mac, Magnum uses a booted iPhone simulator, or boots one, and installs and launches the app there. Its screen shows live in a device tab in the session's place (the tab open on that simulator already, when there is one), the run's output a tab behind; click, drag and type there to use your app, or Open Simulator. Closing the tab leaves the simulator running.

For Android, Magnum uses a running device or emulator, or starts your first virtual device without a window. It needs the Android SDK, from ANDROID_HOME or where Android Studio puts it. Its screen shows in a device tab the same way; there a click taps, a drag swipes, and Back and Home are buttons. Once you've clicked the screen, what you type goes to the device: letters, numbers and punctuation (no accents or emoji, which Android's input doesn't take), Backspace, Delete, Return, Tab, Escape and the arrows.

Agents checking their own work

An agent in any session can use your pages and devices in Magnum's window, so one fixing your app checks its work on the running app while you watch. Its tools (Magnum's, mcp__magnum__… in Claude Code, magnum_… in Pi):

• pages and devices list what's open (a page's id starts with p, a device's with d), and the simulators and emulators installed here.
• open_page opens an address in a browser tab, and open_device a simulator or emulator by name (started if it isn't running), beside the session: with tiles on they join the tiles, otherwise they wait in the strip.
• page_screenshot and device_screenshot give it a picture (also saved under ~/.magnum/reviews/captures, for a review's evidence); page_console reads what the page logged since it loaded.
• page_click (by a CSS selector, the words it says, or a point) and page_type act on a page; device_tap, device_swipe, device_type and device_button (Home; Back on Android) on a device, a tap's place in the pixels of its latest picture.

Left without an id, a tool acts on the session's project's own page (its ▶ Run's) or device, else the only one open. They act only on what's in Magnum's tabs and don't ask first. A session gets them where its machine's node serves them (Magnum's own build does); Balanced leads have them too, beside their workers' tools. An iOS simulator takes an agent's taps, swipes and typing while Magnum drives it natively; one it can't (see Phones) is to look at only.

Shipping

Click the rocket in the toolbar, or choose Ship in ⌘P. Ship needs a repository with an origin, and Claude Code as the project's agent: its rules keep Ship from destroying anything.

The Ship tab opens beside the session with where your work stands and the steps that apply: commit what isn't committed, rebase onto origin's default branch when it moved on, run the repository's check ([worktree] check in .magnum/settings.toml) or the tests, push, and on GitHub, the checks and deployments after.

The push goes straight to the default branch, or through a pull request when that branch's rules or protection require one, your branch already has one, or recent work arrived through pull requests. Hover the push step to see why. Where the repository allows auto-merge, the pull request merges once its checks pass.

Proceed starts a Ship session in the background, in Auto. It can't force-push, hard-reset, delete branches or skip hooks, and it can't push yet. Each step shows as it runs. If it needs you, for a conflict that changes behaviour say, it asks in its session: Open session shows it.

Confirming the push

When all is ready, the rocket turns into an arrow (point at it: Ready to push), and so does a row in Board › Now's queue (Push, Cancel). The Ship tab lists the commits that would go, with Push and Cancel.

Push lets the session push or open the pull request; then it closes, kept in history. On GitHub, Magnum follows the pull request until it merges, then the commit's checks and deployments, for up to an hour, and the Board tells you how it went.

Cancel pushes nothing and puts your work back as it stood before Proceed: the branch on its commit, staged and unstaged changes, untracked files. Files it made that git doesn't track, such as build output, stay. If you changed files since, it says which, and changes nothing.

A Ship that stops without shipping says why, and Put back (Put back as before Ship in ⌘P) puts your work back the same way. Once it's done, the rocket shows a tick (Shipped) or a warning (Not shipped): click it to ship again.

A Ship goes on after Magnum restarts: the rocket and the Ship tab as they were, its session with Ship's guards (pushing still waits for you), Push, Cancel and Put back, its pull request and its rollout watched again.

Pull requests that fix themselves

Magnum looks at the pull requests your sessions opened every 2 minutes, and tells you what's new under Board › Now: checks failed or passed, changes requested, approved, a conflict, a comment, merged, closed. In a pull request's pane, Its session fixes checks, reviews and conflicts (for the whole project, off at first) sends these to the session that opened it instead of leaving them to you: checks failed, changes requested, a merge conflict.

That session gets the request the pane's Fix failing checks, Address reviews or Resolve conflicts would put in its box, with a note to commit and not push, and works on it as a Ship for that pull request: it fixes and commits, but can't push. Then Ship's Ready to push comes to you, as above: Push updates the pull request; Cancel pushes nothing and leaves the session's commit on its branch. The news row says "sent to its session".

It sends nothing to a session on another agent than Claude Code (Ship's guards are Claude Code's), while a Ship is under way in the project or the session is working, when it's closed (unless a Ship opened the pull request: then it's reopened in the background), or after three fixes that day for that pull request: then the news comes only to you, and isn't sent later.