---
name: manage-scheduledtask
description: Create, test, schedule, and troubleshoot recurring agent tasks with the scheduledtask CLI across harnesses (codex, claude-code, opencode, shell). Use when a user wants work to run on a schedule, asks about automations, wants to check an automation inbox, or reports a scheduled run misbehaving.
---

# Manage scheduledtask

scheduledtask runs recurring agent prompts headlessly on any harness. Skills
define the method; scheduled tasks define the schedule.

## CLI reference

```bash
scheduledtask init [dir]        # scaffold .scheduledtask/tasks/ + example
scheduledtask add --name <n> --cron "<expr>" --prompt "..." [--harness codex]
scheduledtask list              # all tasks (repo + user + plugins)
scheduledtask next              # upcoming fire times
scheduledtask run <name>        # fire immediately (test before scheduling!)
scheduledtask daemon            # scheduler loop (30s sweep)
scheduledtask sweep             # single pass, exit
scheduledtask inbox             # recent runs with unread markers
scheduledtask show <id>         # full report for one run
scheduledtask archive|pin|read <id>
scheduledtask pause|resume|remove <name>
scheduledtask doctor            # harness availability check
```

## Task definition format

Files live in `<repo>/.scheduledtask/tasks/<name>.yaml` (file name must equal
`name`), `~/.scheduledtask/tasks/`, or inside agent plugins at
`.agents/plugins/<plugin>/dev.scheduledtask/tasks/`.

```yaml
name: nightly-bugfix
description: Fix bugs introduced by my own commits in the last 24h
schedule:
  rrule: FREQ=DAILY;BYHOUR=3   # or cron: "0 3 * * *"
harness: opencode               # claude-code | codex | opencode | shell
model: opencode/x-preview-f-free
effort: high                    # low | medium | high
sandbox: workspace-write        # read-only | workspace-write | full
mode: standalone                # standalone = fresh context each run
worktree: true                  # isolate each run in a git worktree
dedup: true                     # identical findings -> silent no-change run
catch_up: latest                # latest | all | skip after laptop sleep
notify: [macos]
timeout_minutes: 30
enabled: true
prompt: |
  Check my commits from the last 24h. For each bug you can attribute to my own
  changes, implement a minimal fix and verify it.
```

## Creating a task for someone

1. Interview only for what matters: what to do each run, cadence, which change
   is important enough to report, when to stop or ask.
2. Decide the mode:
   - Each run independent -> `standalone` (fresh session every time).
   - Next check depends on previous work -> `mode: thread` (resumes last
     session where the harness supports it).
3. Write a durable prompt: what to do, what counts as reportable, verification
   commands to run.
4. Test it manually first: `scheduledtask run <name>` — manual runs never move
   the schedule cursor, so testing is always safe.
5. Trust the repo once (`scheduledtask trust`) so its tasks may run unattended.
6. Only then set `enabled: true` and start the daemon.
7. Keep sandbox narrow. Prefer `workspace-write` + git worktrees. `sandbox:
   full` is only allowed for user-authored tasks and should stay that way.

Shell tasks must pass prompts via files: use `{{prompt_file}}` in the command.
Prompt text is never spliced into shell lines (injection safety).

## Troubleshooting

- Runs never fire: is the daemon alive? (`scheduledtask next` shows pending
  slots; missed ones follow `catch_up` policy.)
- Same finding reported daily: keep `dedup: true` and phrase the prompt so
  unchanged state must answer exactly `NO_CHANGES`.
- Run failed: `scheduledtask show <id>` includes stderr; check `doctor` for a
  missing harness binary.
- Wrong timezone firing: schedules are evaluated in local wall-clock time;
  verify with `date` vs `scheduledtask next`.