# Schedules

> Run a command or start an agent session on one of your machines at set times, even when Muxen isn’t open.

A schedule runs a command, or starts an agent session, on one of your machines at set times: run the tests every night, check a disk every hour, have Claude Code go through new issues every weekday morning. It’s kept on the machine and run by the machine’s own scheduler, so it runs whether Muxen is open or not.

![The Schedules page: a Claude Code triage schedule on Forge, Nightly tests and Disk report on Beacon with the nightly run's test output open, and a failed Backups schedule on Vault.](https://muxin.dev/images/shots/schedules-dark.png?v=78ef7981)

*Schedules by machine, each with its last run. Nightly tests is open on its last six runs and the newest one’s output.*

## How it works

1. **You save it**: In the New schedule dialog, from a terminal, or from an agent.
2. **Kept on the machine**: In `~/.muxen/schedules/`, and registered with cron, launchd or Task Scheduler there.
3. **At its time**: The machine’s scheduler runs it through Muxen’s agent, with or without Muxen open.
4. **Output kept there**: Each run’s output stays on the machine; the Schedules page shows it.

*Muxen only edits the schedule. Running it is the machine’s job.*

- **Linux:** cron. Muxen keeps its own block in your crontab and leaves the rest alone.
- **A Mac:** launchd, as a LaunchAgent of yours.
- **Windows:** Task Scheduler, in a `\Muxen\` folder, without a window popping up.

Times are in the machine’s own time zone, not your computer’s.

## Make one

Click **New schedule** on the Schedules page (`⌃7`), or right-click a machine › **New schedule here…**.

![The New schedule dialog: Name, On (the machine), Runs (A command or An agent session), Folder, and When, with Every day at 09:00 picked.](https://muxin.dev/images/shots/scheddlg-dark.png?v=674575d8)

*It’s kept and run on the machine itself.*

- **Name**: what it’s called on the Schedules page.
- **On**: the machine it runs on.
- **Runs**: **A command**, run in your login shell there, or **An agent session**: pick an agent and a prompt, and at its time it starts a session like New session does.
- **Folder**: where it runs. Your home folder when empty.
- **When**: every 1 to 59 minutes, every hour (on the hour), every day, weekdays, or some days of the week, at a time like 09:00.

## Command or agent session?

An **agent session** starts a real session, the same as one you’d start yourself. It shows up under the machine in the sidebar, and waits for you when it’s done. Good for work you want to look at and answer: “go through new issues and draft replies”.

For an agent that should work on its own and just finish, use a **command** that runs the agent without a terminal, like `claude -p "label the new issues in acme/api"`. Its output is kept like any command’s.

## The Schedules page

Schedules are grouped by machine, and each machine says what runs them (“Run by cron”, “Run by launchd”, “Run by Task Scheduler”). Each schedule shows when it runs and how its last run went.

- **Run now** runs it once, now.
- **Pause** stops it running until you **Resume** it.
- The bin deletes it, with its runs.
- **Click a schedule** to see its last runs, newest first, and pick one for its output: what it printed, how long it took and its exit status. For an agent session, the session it started, with **Open it**.

## Good to know

- The last 30 runs of each schedule are kept.
- A command that’s still running after 6 hours is ended.
- If a run is still going when the next one is due, the next one is skipped.

> **Warning:** On Linux, schedules need cron installed and running. Containers often have none. When a machine can’t run them, Muxen says why on the Schedules page, with what to do (for example `sudo systemctl enable --now cron`).

## From a terminal and from agents

```
muxen schedule add beacon --name "Disk report" --every weekdays --at 09:00 --command "df -h /"
muxen schedule add beacon --name Triage --every day --at 08:30 --agent claude --prompt "Label new issues in acme/api"
muxen schedule add beacon --name Backups --every 2h --command "restic backup ~/data"
muxen schedule ls                   # every machine’s (--on beacon for one)
muxen schedule run beacon s-ab12cd  # run it now
muxen schedule log beacon s-ab12cd  # its last runs and output
muxen schedule rm beacon s-ab12cd
```

`--every` takes `15m`, `2h`, `day`, `weekdays` or days like `mon,thu`. Agents use `schedule_list`, `schedule_save`, `schedule_run`, `schedule_log` and `schedule_delete`. See [The command line](https://muxin.dev/docs/cli) and [MCP for your agents](https://muxin.dev/docs/agents).