Automations

Automations

An automation is a list of steps Magnum goes through for you: when you say so, or on a schedule, with Magnum open or closed. Each step is one of Magnum's actions, and a session is one kind of step. This is the first cut: six actions, Run now and a schedule, and the steps are written in a file.

Automations in the sidebar

The switch at the top of the sidebar has Automations beside Projects and Machines (also ⌘P, Show automations in the sidebar). Each automation is a row: how its latest run stands, its name, its project and when it starts next. Another machine's automations are under that machine's name. Right-click a row to run or stop it, turn its schedule off or on, show its file, or delete it.

New automation, at the foot of the sidebar, writes a starter for the project that's open, on that project's machine, and opens it. The starter is Dependency audit: a session that updates what is safe to update, then a draft pull request, on weekdays at 09:00.

An automation's tab

Click an automation to open it in a tab, beside your sessions and terminals. Its steps are listed in order, each with what it's set to and its text. Run now starts a run; Stop ends it. While a run goes, each step shows how far it got, what it gave, and what it spent. Under the steps are its runs: click one to see how its steps went.

The steps are read-only in the tab. To change them, edit the file; the tab follows within a few seconds.

The file

An automation is a file on the machine that runs it: ~/.magnum/automations/<name>.toml.

name = "Dependency audit"
project = "/Users/me/code/app"
when = "weekdays 09:00"

[[step]]
do = "session"
gives = "audit"
prompt = "Update what is safe to update, run the tests, commit."

[[step]]
do = "open_pr"
title = "Dependency audit"
body = "{audit}"

project is the project's folder on that machine, from the top. when is optional: daily 09:00, weekdays 18:30, every 30 minutes, every 2 hours or once 2026-12-01 09:00, in that machine's time. Without it, the automation runs only when you run it.

A file Magnum can't read is listed with what's wrong and the step it's in.

Steps

Each [[step]] names an action with do:

A step with gives = "name" passes its value on: later steps' text has it as {name}. A session gives what it said last, a command what it printed, open_pr the pull request's address. {project}, {branch}, {worktree} and {pr} are there too.

Where a run works

A run works in a worktree of the project, on a branch of its own (auto-<name>), made when its first session starts; your own folder isn't touched. A worktree nothing was committed in is removed when the run ends.

A session step edits without asking in that worktree, and may commit. Anything else it asks to do waits for you: the automation shows it needs you, and its tab has Allow and Deny. allow in the step lets it through without asking.

The repository's own commands (its worktree setup, its check) run only once you allow them for the project: the tab asks, with the command.

Schedules and restarts

One run of an automation goes at a time. A time missed while the machine was off or asleep starts one run when it's back, not one for each. The switch in the tab turns the schedule off; Run now still works.

Automations run in Magnum's background node, so they go on with Magnum's window closed. On a Mac the node stays in the menu bar while an automation has a schedule or a run is under way; after the Mac restarts, it starts again when Magnum is opened. On a server whose node runs as a service, it's always there.

A run under way when the node shuts down is picked up where it was when the node starts again: its session is resumed and told to carry on.

When a run ends

When a run ends, Magnum tells you: what its last step gave (the pull request, when one was opened), or the step that failed and why. A step that fails ends the run; the steps after it are skipped. An ask step shows under what needs you.