Run agents on a schedule

1How it works

A schedule is a prompt, an agent, a folder and a time. When the time comes, diri opens the agent in that folder and sends it the prompt, just as if you had typed it.

diri keeps the schedule, not the agent that made it. It keeps working after you close that conversation, quit the app window or restart diri. The only thing it needs is diri running on your Mac at the time, and even that has a fallback: a run the Mac slept through starts as soon as it is back.

2Ask an agent for a schedule

The quickest way is to ask the agent you are already talking to. Say what to do, when, and where the result should go. Starting with “Use diri to…” makes sure it uses diri’s schedule instead of a timer of its own.

The agent answers with the schedule in plain words, for example “Weekdays at 09:00, next run Monday at 09:00. It will wake the Mac.” If that is not what you meant, say so and it will fix it.

3Or set one up yourself

1. Open Settings → Schedules and click New schedule.
2. Under Prompt, write what the agent should do.
3. Pick the Agent, and click Choose… to pick the Folder it works in.
4. Under When, pick Once, Every day, Weekdays or Every hour, and type a time such as 9:00 or 17:30.
5. Click Create schedule.

Agents can set up any timing, such as Mondays and Thursdays at 8:30 or every 15 minutes. The form keeps it simple; schedules made by agents show up in the same list either way.

4What each run does

The first run opens a new tab with the agent, in the chosen folder, and sends the prompt. Later runs send the prompt again into that same tab, so a daily schedule is one ongoing conversation instead of a pile of tabs. If the agent had quit, diri resumes it first. If it is still busy with the last run, the new one waits for it to finish.

Close the tab and the next run simply opens a new one. Schedules that use a fresh worktree are different: every run gets its own clean copy of the project and its own tab, so one night’s work never mixes with the next.

A session started by a schedule shows a small clock after its title in the sidebar. Hover it to see which schedule started it and when the run was due. The clock is indigo when diri woke the Mac for that run.

• Write a prompt that stands on its own. The first run cannot see the conversation where you made the schedule. Say what to do, where things are, and what to produce.
• Say where the result goes. A file, a pull request or a note is easy to find in the morning. “Tell me” only works if you read that tab.
• Use a fresh worktree for code changes. Each run then starts from a clean checkout and leaves its work on its own branch.

5When the Mac is asleep

If the Mac was asleep or diri was closed at the due time, the run starts once as soon as both are back, up to 12 hours late. Older missed runs do not pile up: a whole closed weekend becomes one run on Monday, and nothing ever runs twice for the same time. Turn off Catch up if missed on a schedule if a late run would be useless.

Two switches in Settings → Schedules, under When the Mac is asleep or restarts, cover the rest:

Open diri at login

Schedules run only while diri is open. With this on, a run missed during a restart catches up after you log in.

Allow diri to wake the Mac

Installs a small helper that can only set wakes for your runs. macOS asks an administrator to approve it once in System Settings → General → Login Items.

Then turn on Wake the Mac for a schedule, or ask the agent to. diri wakes the Mac 2 minutes early, keeps it awake while the agent works, and puts it back to sleep afterwards, unless you started using it or another agent still needs you.

6Check, pause and remove

Settings → Schedules lists every schedule with its next run and one line about the last one, such as “Last ran today at 09:00” or “Ran late because the Mac was asleep”. Each row has Open to jump to the tab its last run used, Run now, Delete, and a switch to pause it.

You can also ask:

Deleting a schedule stops future runs. Tabs its earlier runs opened stay where they are.

7For developers: the MCP tools

Agents make schedules through diri’s MCP server, dirijor. Claude Code, Codex and Cursor get it automatically when diri starts them; other agents can connect to it in a minute. The server tells agents to use these tools instead of their own cron or loop features, which stop when their session closes and skip runs the Mac slept through.

schedule_agent

Creates a schedule. Returns the next due time.

list_schedules

Every schedule with its next run, recent runs (on time, late, missed, failed or by hand) and the session each run used.

delete_schedule

Removes a schedule by id. Its sessions stay.

A typical schedule_agent call from the first example above:

{
  "name": "Morning issue triage",
  "kind": "claude",
  "cwd": "/Users/you/code/app",
  "prompt": "Read the GitHub issues opened since the last run, label each one, and add a short triage summary to triage.md.",
  "cron": "0 9 * * 1-5",
  "wake_mac": true
}

kind, cwd and prompt are required. For the time, pass exactly one of:

cron

Five fields in the Mac’s local time. 0 9 * * 1-5 is weekdays at 9:00, 30 8 * * * every day at 8:30, */15 * * * * every 15 minutes.

in_minutes

Once, this many minutes from now.

at_ms

Once, at an exact moment in epoch milliseconds.

The optional arguments match the switches in Settings: catch_up_hours (0 to 168, default 12, 0 never catches up), keep_awake, wake_mac, and worktree with base (for example origin/main) for a clean checkout every run. If list_schedules reports a wakeHelperError, the wake helper has not been approved yet.

You can call the same tools from a terminal with the dirijor CLI:

echo '{}' | dirijor mcp-call --tool list_schedules

Every argument is in the MCP tool reference, and every setting in the schedules docs.