Automations

What Is an Automation?

An automation is a named task tied to one device — your Mac or a paired Linux box — that runs either when you trigger it or on a cron schedule you set in that device's local time. It keeps running whether Spaces is open or quit, and a remote automation keeps its own schedule even while your Mac is asleep. There are two kinds: an Agent automation spawns a coding agent into a workspace and hands it a prompt; a Script automation runs any shell command. The Automations row sits directly below Alerts in the sidebar and merges automations and runs across every paired device into one pane, with a device filter for when more than one is connected.

Schedule an Agent

The fastest way to use Automations: give it a name, pick a workspace, write a prompt, and set a schedule (or leave it Manual and run it whenever you like). No shell script, no cron syntax to memorize unless you want it.

• WorkspaceWhere the agent spawns — the same working directory you'd pick for any other session in that project.
• Agent commandDefaults to claude, and may carry flags (e.g. --model). Also works with codex and opencode.
• PromptPlain multiline text, sent to the agent verbatim once it's up and ready to work.

When an automation fires, the agent spawns into that workspace exactly as if you'd started it yourself — its permission prompts show up in its own terminal, and it appears in Coding Agents and Alerts like any agent you launched by hand. You can even find its terminal the normal way, right inside that workspace, in addition to the Automations pane. Once it reports it's done, the run finishes as succeeded — its terminal is left open on purpose so you can read what it did; Spaces never closes a finished agent's session for you. If it ends up blocked waiting on your approval instead, that surfaces as a normal agent alert, same as any other agent.

Because the agent's session outlives the run, a schedule set to Skip or Queue treats that lingering session as still going: it keeps recording skipped runs, or holding the next one queued, until the session ends on its own — or you close it, or use End agents on the run to reap it yourself. Nothing ever kills a live agent automatically.

Script Automations

For anything a single prompt doesn't cover — a maintenance job, a health check, an orchestrator that fans work out to several agents itself — a Script automation runs plain multiline shell text in the device's login shell, from a working directory you type or, on the local device, pick with a folder browser. Point it at a script file you already have with zsh ./file.sh instead of pasting the whole thing inline.

Switching an Agent automation to Script prefills the editor with the equivalent CLI — spawning the agent, then sending the prompt — a starting point for a script that needs to do more than deliver one prompt (see Orchestrated batch below).

Trigger, Concurrency, and Timeout

These fields work the same way for either kind.

• TriggerManual, or Cron. A cron trigger offers preset builders — every N minutes, hourly at a minute, daily at a time, weekly on chosen days at a time — plus an Advanced mode for a raw 5-field cron expression. Whichever you use, the form previews the next three run times and flags a parse error inline.
• Concurrency policyWhat happens when a fire lands while an earlier run of the same automation is still going (for an agent automation, that includes its spawned agent's session still being open). Allow always starts a new run alongside it — for independent runs that never share state. Skip records a skipped run instead of starting a new one — for a periodic check where two overlapping copies would waste resources or double up alerts. Queue holds at most one run to start right after the current one finishes — for a workflow where every tick should eventually happen; a fire that arrives while one is already queued is skipped rather than piling up further.
• Missed-run policyWhat a restarted daemon does with a cron fire that elapsed while it was down. Run once fires a single catch-up run regardless of how many occurrences were missed. Skip records one skipped run instead. Either way the next fire time is recomputed from now.
• TimeoutAn optional wall-clock budget. A run over budget is asked to stop and, if it doesn't, force-stopped shortly after.

Runs

The Runs tab lists every run of every automation, newest first, with its status, trigger (manual, cron, or a missed-run catch-up), start time, duration, and exit code; a skipped run shows why it was skipped. Open a running run to watch its live terminal exactly as it executes, or an ended run to replay its output read-only. A run can end succeeded, failed with its exit code, timed out, or canceled — cancel is available on any run that is still going. A failed or timed-out run also raises a dismissible entry in Alerts, naming the automation, the failure, and the device, that opens straight to that run.

Any coding agents a run is responsible for — an agent automation's own agent, or one a script automation spawned itself — show up as chips on the run with a live status dot; clicking one opens that agent's terminal. A run that has finished but still has a live agent lingering offers End agents to stop it and finalize things, without touching the run's own status.

Spaces keeps the newest 100 runs of each automation and prunes older ones together with their saved logs, so run history stays useful without growing unbounded.

On iPhone

The Automations tab on iOS shows the paired device's automations and lets you run one now or cancel one that's running — creating, editing, and deleting an automation stay Mac-only. Each row shows a status dot for its most recent run, its trigger, the next fire time, and whether it's disabled; tapping a row runs it, and the outcome (started, queued, or skipped) shows through the row once the list refreshes. A Runs screen lists every run the same way the Mac Runs tab does, with a Cancel action on a running one and an End agents action on a finished one with a lingering agent — iOS shows status only, with no terminal or replay view. The tab badges how many runs are currently in flight on the device.

Example Patterns

Four patterns to copy and adapt. Two are Agent automations you set up entirely in the form; the other two are Script automations for cases that need more than one prompt.

git fetch --prune && ./scripts/audit.sh

Review project status and identify next actions

claude -p "$(cat prompt.md)"

STATE_FILE="$HOME/.spaces/poll-session-id"
WORKSPACE_ID="<workspace-id>"

if [ -f "$STATE_FILE" ] && spaces agent status --session "$(cat "$STATE_FILE")" >/dev/null 2>&1; then
  SESSION_ID=$(cat "$STATE_FILE")
else
  SESSION_ID=$(spaces agent spawn --workspace "$WORKSPACE_ID" --command "claude --resume" --title poll-session | cut -f1)
  echo "$SESSION_ID" > "$STATE_FILE"
fi

spaces terminal send text "$SESSION_ID" "Check the queue and process the next item." --submit

The Orchestrated batch pattern runs a coding agent non-interactively (prompt.md holds the orchestration instructions — see Agent Orchestration for a starting point), which means there's no one at the keyboard to approve its spaces CLI calls as it spawns and manages worker agents. Pre-approve those tool calls in the agent's own permission settings before scheduling it, and set a timeout so a batch that runs long or hangs doesn't run forever.

See Also

• • Coding Agents — how agent state, hooks, and Alerts work for any agent, spawned or not.
• • Agent Orchestration — the copy-paste orchestrator prompt behind the orchestrated-batch pattern.
• • CLI Reference — full flags for spaces agent spawn and spaces terminal send.
• • iOS App — pairing a device so its Automations screen can view, trigger, and cancel runs.