CodeHerderSearch⌘KRequest access →

Scheduled tasks

Create a recurring task that runs on a cron schedule. Each run makes an ordinary task with a repo and a base branch.

A scheduled task turns recurring work into a first-class object. Instead of a person remembering to re-file the same task every Monday — a nightly report, a weekly dependency audit, a periodic cleanup sweep — you define the work once, attach a cadence, and let CodeHerder file it for you.

What a scheduled task is

A schedule is a recurring producer of ordinary tasks. It stores a frozen copy of the inputs a normal task takes, plus a cron expression. When the cadence fires, the scheduler creates a single, ordinary task from those stored inputs — and then does nothing else.

That spawned task is indistinguishable from a hand-filed one. The existing workflow engine picks it up, staffs it, and runs it through its stages exactly as described in How work flows. The scheduler is only a producer; it adds no new execution semantics.

Each spawned task records which schedule produced it, so it shows up in the activity feed and in a schedule’s Recent runs list. The schedule also appears as a connection in the spawned task’s own lineage — see Where a task came from for how that differs from the task’s Origin row.

Creating a schedule

A schedule takes the same inputs as a task, plus the cadence:

  • The task inputs — title, description, priority, workflow, and any required capabilities. These are frozen into the schedule and reused on every fire (see Core concepts for what each means). A schedule can carry two kinds of capability, the same as a task: agent capabilities (what an agent’s launch config must cover to run the spawned tasks) and device capabilities (what device they must place on). See Capabilities for the difference.

    Requiring agent capabilities needs the Capability routing feature on your plan (see Plans and limits). Creating or editing a schedule with agent capabilities runs the same check as ch task create/ch task edit: it’s rejected if no launch config in your workspace covers the set, unless your workspace has no launch configs yet, in which case the check is skipped. CodeHerder repeats this check on every fire, so a plan change or a launch-config change after you save the schedule can make a later fire fail (see How schedules behave, below). Device capabilities only get a shape check, not a fleet check — a schedule can still spawn tasks that no device can ever be placed on if none advertises the tokens you set.

  • A cron expression — a standard five-field cron string (for example 0 9 * * MON for 9 a.m. every Monday). CodeHerder refuses an expression that never matches a real date, such as 0 9 30 2 * (30 February), when you save. The named shorthands @hourly, @daily, @weekly, @monthly, and @yearly are also accepted.

  • A timezone — an IANA timezone name (for example Europe/London), defaulting to UTC. Cron without a timezone is ambiguous, so the schedule always carries one; daylight-saving transitions are handled for you.

  • Enabled or disabled — disable a schedule to pause it without deleting it, and re-enable it to resume. A disabled schedule never fires automatically.

  • An optional due-offset — make each spawned task due a fixed interval after it is created (for example “due 2 days after spawn”). An absolute due date would be in the past after the first fire, so the offset is relative. The web form asks for this offset in hours; the CLI takes a duration like 2h or 7d instead.

  • A repo set — the repositories each spawned task starts with, from none up to several. With no repo set, each spawned task uses CodeHerder’s automatic choice when it starts. Leaving the web form’s Repos picker empty does the same. Pass --no-repo on ch schedule create or ch schedule edit for tasks that need no checkout. See Tasks that span several repositories for what a repo set is and how a task uses it.

  • An optional base branch — where each spawned task’s sandbox branches from, and where its merge requests land, instead of each repo’s own default branch. See Choosing a task’s base branch.

  • Optional pre-filled fields — you can seed a canned field value, such as a standing proposal, that is written onto every spawned task. A field key must be one the schedule’s workflow declares; naming one it doesn’t is rejected when you save the schedule, not when it later fires.

  • An optional end date — set a date and time after which the schedule stops firing automatically. Once that moment passes the schedule remains in your list but will not fire again; push the end date further out (or clear it) to resume firing. The web form reads the date in the schedule’s own time zone. Set it in the web app when you create a schedule, and add, change, or clear it any time afterwards from the web app or the CLI — see From the CLI, below.

For example, a weekly dependency audit against one repo:

ch schedule create --title "Weekly dependency audit" --cron "0 9 * * MON" \
                    --type story --repo api --description-file audit-brief.md

Every Monday at 9 a.m. this spawns a new task against the api repo, ready for an agent to pick up and work through the normal workflow.

Turning a task into a schedule

If you already have a task that turned out to be recurring work, you don’t have to rebuild it as a schedule from scratch. Both the web app and the CLI can seed a new schedule directly from an existing task.

In the web app: open the task and choose Make it recurring from the task’s More menu. A panel opens on the task page and asks for a cron expression (required) and, optionally, a timezone (defaults to UTC) and a title (blank reuses the task’s own title). It shows a Next 3 runs preview as you type. Select Create schedule to create it and open its page. The panel always creates an enabled schedule. To create it paused, use --disabled from the CLI.

From the CLI:

ch task schedule <taskId> --cron "0 9 * * MON" [--tz <IANA>] [--title "<title>"] [--disabled]

--disabled creates the schedule paused, the same as on ch schedule create. On success the CLI prints the new schedule’s ID.

What carries over: title, description, priority, workflow, agent and device capabilities, the repo set (any archived repo is dropped), the no-checkout setting, the base branch, and the value of every field that no workflow stage writes. A field a stage writes, a prototype field, and a child-task field are skipped. A checklist field carries over with every item unchecked, so the new schedule’s spawned tasks start with a fresh checklist each time.

What’s dropped: a schedule has no concept of a parent task, a dependency, or a due date. The panel lists which of these the source task actually has set, under “Making this task recurring drops:”, before you submit, so you know what you’re leaving behind. The CLI prints the same list as warnings while it creates the schedule. The new schedule also starts with no due offset and no end date — add either afterwards with ch schedule edit or the web app’s edit form.

Where it lives

In the web app

Open Tasks, then select Schedules in the page header. From there you can:

  • see every schedule with its Type (the workflow), a Created date, last run (Never before its first fire), and next run (blank while the schedule is disabled), and a Schedule column with a plain-language summary of the cadence (for example “Every day at 03:00”) above the raw cron expression, with the timezone beside it — a cron expression too complex to summarize plainly just shows the cron and timezone on their own,
  • create one (the form reuses the New Task fields — including its repo set and base branch — and adds the cron expression, timezone, an Enabled (start firing immediately) checkbox on create, due-offset in hours, task-field seeds, and end date). Workflow is a required card picker, as on New task. It lists only enabled workflows. The form preselects task, else story, else the first one listed, as New task does. Change it if you want another. If your workspace has no enabled workflow, you can’t create a schedule. The timezone list holds common zones; the CLI’s --tz accepts any IANA name. The form groups its fields under Schedule, Task, Timing, and Placement, and shows a Next 3 runs preview in your own timezone that updates as you type. If the cron expression is invalid, the preview says why,
  • pause a schedule by disabling it (or resume by re-enabling), edit it — including its repo set, base branch, and end date — or delete it,
  • run it now (More, then Run now on the list, or Run now on a schedule’s page, uses the schedule’s saved inputs; for one-off changes, use ch schedule run-now — see From the CLI), and
  • open a schedule to see its Recent runs — up to the 10 most recent tasks it has spawned. Each run also shows a filed summary, such as “3 filed: 2 code, 1 review” (ch schedule show prints the raw status names) — the tasks an agent filed while working that run’s task, in the schedule’s own workspace. Below the summary, up to 20 of those filed tasks are listed newest first with a status badge; if the run filed more than that, the list ends with “and N more”. See Where a task came from for what “filed” means.

A Times in switch (your time, the schedule’s zone, or UTC) on the list and on a schedule’s page changes only how times display. It never changes when the schedule fires.

A schedule’s pause, edit, delete, and run-now controls only appear for members who can actually use them — see Who can change a schedule below.

From the CLI

The ch schedule verb group mirrors the web app. Everywhere below, <id> also accepts the schedule’s title instead of its full ID — see Using the ch CLI for how CodeHerder matches a record by name.

ch schedule create  --title "<title>" --cron "<expr>" [--tz <IANA>] [--priority high|normal|low]
                     [--type <type>] [--cap <capability> …] [--device-cap <capability> …]
                     [--due-in <duration>] [--disabled] [--description <text>]
                     [--repo <ref>] … [--no-repo] [--base-branch <branch>]
                     [--field <key>=<value>] … [--field-file <key>=<path|->] …
ch schedule list     [--enabled | --disabled] [--failing] [--limit N] [--cursor <token>]
ch schedule show     <id>          # next/last run, last error, recently spawned tasks (with what each filed), stored field seeds
ch schedule edit     <id> [--title <t>] [--cron …] [--tz …] [--priority …] [--type …]
                     [--cap <capability> … | --clear-caps]
                     [--device-cap <capability> … | --clear-device-caps]
                     [--due-in <duration>|""] [--description <text>] [--ends-at <RFC3339>|""]
                     [--repo <ref>] … [--no-repo] [--base-branch <branch>|""]
                     [--field <key>=<value>] … [--field-file <key>=<path|->] …  # alias: update
ch schedule enable   <id>          # resume: turn automatic firing back on
ch schedule disable  <id>          # pause: stop automatic firing without deleting it
ch schedule delete   <id>
ch schedule run-now  <id> [--field <key>=<value>] … [--field-file <key>=<path|->] … [--description <text>|""]

--cap and --device-cap are both repeatable and, on edit, replace the whole set — the same as --repo below. --clear-caps empties the agent-capability set and --clear-device-caps empties the device-capability set; each is mutually exclusive with its own --cap/--device-cap flag on that call. ch schedule show <id> prints a type row and, when the cron expression has a plain-language summary (see In the web app, above), a runs row right after the cron row. The type row reads task (default) when the schedule names no workflow. The web app shows a plain Task badge. The web edit form requires a workflow. Pick one before you save such a schedule there.

Its RECENT RUNS table adds a FILED column, and for each run that filed anything, the command prints a block underneath headed FILED BY RUN <runId> (<title>) listing what that run filed, newest first. When a run filed more than 20 tasks, the block ends with a line like … 5 more (ch task lineage <runId> --direction down), pointing you at the full list. See Where a task came from for what “filed” means.

Use ch schedule enable <id> and ch schedule disable <id> to pause or resume a schedule — these are the canonical way to flip a schedule’s enabled state from the CLI. ch schedule list --enabled/--disabled reads that same state back, narrowing the list instead of changing it — see Listing enabled and disabled records.

Spotting a schedule that needs attention

The schedules list shows a status badge under each Last run: none, running, blocked, done, cancelled, or failed. Blocked means the run’s task sits in a blocked stage or has an open blocker. Hover a blocked badge to see the reason. Failed means the run ended in a workflow end stage that isn’t a success. Cancelled covers cancelled and archived tasks. A “last error” line appears under the schedule’s name when the last fire failed.

Turn on the Failing toggle to show only schedules whose last run is blocked, failed, or cancelled. It combines with the All, Enabled, and Disabled switch and with search. From the CLI, ch schedule list --failing does the same, and the list prints a LAST STATUS column. The status shows on the list only, not on a schedule’s own page.

A schedule’s page shows the full last error in a callout, and ch schedule show prints it as an error row. The next successful fire clears it.

Setting an end date from the CLI. ch schedule edit sets or clears a schedule’s end date; ch schedule create has no end-date flag, so give a brand-new schedule an end date either in the web app’s create form or by running ch schedule edit right after you create it.

ch schedule edit <id> --ends-at 2026-12-31T23:59:00Z   # stop firing after this moment (RFC3339)
ch schedule edit <id> --ends-at ""                      # clear the end date — resume firing indefinitely

The timestamp must be an RFC3339 timestamp (include a timezone offset or Z); an empty string clears the end date, and the server refuses a malformed timestamp.

Clearing the due offset from the CLI. ch schedule edit <id> --due-in "" clears the due offset, the same way --ends-at "" clears the end date — spawned tasks go back to having no due date. Omitting --due-in on edit leaves the current offset unchanged.

Setting a repo set or base branch from the CLI. --repo <ref> takes a repo’s name or ID; repeat it to attach more than one, the same as ch task create (see Tasks that span several repositories). On ch schedule edit, --repo replaces the whole repo set rather than adding to it — pass every repo you want the schedule to keep, not only the one you’re changing. --base-branch <branch> sets the branch each spawned task’s sandbox starts from. On edit, --base-branch "" clears it back to each repo’s own default branch, the same as never setting one. Omitting either flag on edit leaves the current value unchanged.

ch schedule edit <id> --repo api --repo web-client   # the schedule's repo set is now exactly these two
ch schedule edit <id> --base-branch ""                # spawned tasks fall back to each repo's default branch

Running once with different inputs. ch schedule run-now can override a schedule’s inputs for a single run. The overrides apply to that one run only. The saved schedule does not change, and the next automatic run or a plain run-now uses the saved inputs again.

ch schedule run-now "Weekly dependency audit" --field focus="security fixes only"
ch schedule run-now "Weekly dependency audit" --description "Just check the payments repo."

Here focus stands for a field that your schedule’s type declares. See Seeding task fields for what a seed is.

  • --field <key>=<value> is repeatable. Each one replaces only its own key, and every other saved seed keeps its value. You can also set a field the schedule has no seed for, as long as the type declares it.
  • --field-file <key>=<path> is the same, but reads the value from a file, or from standard input when the path is -. Use it for a multi-line value such as a checklist.
  • --field key= with an empty value is an error on run-now. On ch schedule edit, the same form removes the seed.
  • --description "<text>" sets the description for this run. --description "" gives this run an empty description. If you leave the flag out, the run keeps the saved description.
  • CodeHerder checks the overrides first. An invalid one is refused before any task is created, and the schedule records no error.

The command prints the new task, then one Override: line for each field you changed, and one for the description if you changed it.

As elsewhere in the CLI, a multi-line description (--description) is passed with --description-file or on stdin, never inline.

Who can change a schedule

Any workspace member can create a schedule and see, list, and open every schedule in the workspace — creating your own recurring automation is self-service.

Changing one that already exists is tighter: editing, pausing, resuming, deleting, or running a schedule requires you to be the schedule’s owner, or a workspace owner or admin. The owner starts out as the member who created the schedule, and it can change (see below). Pausing and resuming count as a change here too, the same as editing or deleting — it isn’t only the destructive actions that are gated.

A member who isn’t the schedule’s owner, and isn’t a workspace owner or admin, sees that schedule’s page as a read-only view. A notice says that managing it requires its creator or a workspace owner or admin. Here, “creator” means the schedule’s current owner. On the list, the row controls simply don’t appear (see Why a control is missing). The equivalent CLI command (edit, enable, disable, delete, run-now) is refused with a permission error the same way. There’s also a broader rule that has nothing to do with ownership: an agent can’t create or change a schedule from inside a task or sandbox session, even one with member access. You can manage a schedule from the web app, from the CLI with your own login, or from a work session you started yourself. The usual owner-or-admin rule still applies.

Ownership moves when someone else edits. When a member other than the schedule’s owner changes it, that member becomes the owner. Pausing and resuming count as changes, so an admin who selects Enable or runs ch schedule enable takes ownership too. Run now does not change the owner. The owner matters because every automatic fire runs with the owner’s access (see How schedules behave, below).

See Members, teams, and roles for what the admin and owner roles can otherwise do.

Seeding task fields

A schedule can pre-fill task fields on every task it spawns — for example, a standing proposal or a recurring checklist item. CodeHerder writes each seed onto the spawned task at creation time; the assignee or agent can then edit those values normally.

In the web app: once you pick a workflow in the create or edit form, the Task group shows a “Task field seeds” hint with one text box per field defined by that workflow. A second line lists fields that can’t be seeded because each run produces them. Changing the workflow clears any seeds you already entered. Enter the value you want pre-populated on every spawned task. A checklist field takes the same - [ ] item and ## <stage> text; leave a box empty to skip that field. Child-task fields are not seedable and do not appear in the list. On the edit form, clearing a seed box and saving removes that seed: tasks spawned after that point will no longer have that field pre-filled.

From the CLI: ch schedule create and ch schedule edit set the spawned task’s description with --description. A per-type field seed (such as a standing proposal or checklist) is set with --field <key>=<value>, repeatable for more than one; the key must be one the schedule’s workflow declares — an unknown key is rejected with an error naming the field, the same check the web app’s seed form applies. On edit, --field merges into the stored seeds rather than replacing them: --field key= (an empty value) removes that one seed, and every other stored seed is left alone. ch schedule show <id> prints every stored seed under a FIELD SEEDS section. A checklist field takes the same text as ch task edit: - [ ] item lines, optionally under ## <stage> headings. A line that is neither fails the command before anything is written. For a multi-line checklist, read it from a file:

ch schedule create --title "Nightly sweep" --cron "0 2 * * *" --type story --field-file acceptance=criteria.md

Here acceptance stands for a checklist field your type declares. --field-file works the same on edit and run-now. Do not pass the same key with both --field and --field-file. To change a seed for one run only, use ch schedule run-now <id> --field <key>=<value>; it never writes the value back to the schedule.

There’s one exception: ch task schedule (see Turning a task into a schedule, above) does carry a source task’s own field values over onto the new schedule, since it’s seeding the schedule from a task that already has them set — it just can’t add or change seeds that aren’t already on that task.

How schedules behave

A few behaviours are worth knowing before you rely on a schedule:

  • Fire-once on catch-up — no backfill. If the server is down across several intervals, the schedule fires once when it comes back and then computes its next run forward from that point. It does not replay every missed interval, so an outage never produces a storm of tasks.
  • One open task at a time. A schedule will not spawn a new task while a task it previously spawned is still open. If the cron fires while that prior task is still running, the fire is skipped silently — no error is raised, the schedule’s last-run time does not update, and the skipped fire does not appear in Recent runs. The schedule simply re-evaluates at its next cron slot and spawns again once the prior task is done, cancelled, or archived.
  • Cron is minute-resolution. The finest cadence a cron expression can express is once per minute. The schedule form advises at least five minutes between fires.
  • Run-now bypasses enabled and the end date, but not the open-task guard. Running a schedule manually fires it immediately even when it is disabled, or after its end date has passed — handy for testing a schedule before you turn it on. Run-now is still subject to the same one-open-task guard, but unlike a skipped automatic fire, it tells you: if a prior task from this schedule is still open, run-now refuses and says so, rather than quietly creating a duplicate. Wait for that task to finish, or cancel it, then run-now again — or just let the schedule’s own next cron fire pick it up. A manual run does not move the next scheduled fire. From the CLI, run-now can also take one-off inputs; a bad override is refused before any task is created.
  • An automatic fire runs as the schedule’s owner. The spawned task is filed in the owner’s name, and the owner’s access decides whether the fire can go ahead. If the owner is disabled or no longer holds a role in the workspace, the fire fails. It also fails if an operator ran ch human revoke-all on the owner after they took ownership (see Credentials and profiles). The schedule’s last error reads “the member who created this schedule no longer has access to this workspace; the schedule is disabled”, and CodeHerder disables the schedule. A schedule with no recorded owner is refused and disabled the same way. To recover, a workspace owner or admin edits the schedule, or re-enables it with Enable or ch schedule enable. That person becomes the owner (see Who can change a schedule, above), and the next fire runs as them. Run now is different: it runs as the person who starts it.
  • Every fire re-checks the rules for creating a task. The fire is refused if the owner would be refused for the same task today: the task-creation rate limit, the Capability routing feature on your plan, launch-config coverage of the required capabilities, or a pre-filled field the type no longer declares. The schedule stays enabled. The last error reads “the schedule’s task was refused: “ followed by the reason. It shows on the schedule’s page and in ch schedule show <id>. Run now returns the same refusal that ch task create would show. To recover, fix the cause (for example, change the schedule’s capabilities or seeds) and let the next fire run.
  • Disabling the workflow a schedule depends on is refused, unless forced. If you try to disable a workflow (type) that an enabled schedule still resolves to, the disable is refused. A schedule with no type set uses the default task type, so disabling task is also refused while such a schedule is enabled. The web app shows an error naming the conflict. From the CLI, ch workspace workflow disable <type> lists every schedule still blocking it, and ch workspace workflow disable <type> --force disables the type anyway. See Task types for the full disable/restore flow. Forcing it through doesn’t stop those schedules: each keeps firing on its own cadence, but every fire now fails, and the failure shows as the schedule’s last error.
  • An unusable repo blocks a fire, not the schedule. A repo can go bad after the schedule was written — it gets archived, or it stops being reachable from this workspace. Every fire re-checks the whole repo set first. If any repo in it has gone bad, that fire spawns nothing and records the reason instead of creating a task with a wrong or missing repo. You’ll see the reason on the schedule’s page and in ch schedule show <id>. Running the schedule manually against the same set is refused the same way, instead of quietly creating a broken task. To recover, select Remove beside the unusable repo in the schedule’s Repos picker (it stays listed and marked unavailable until you do) and save — or replace the repo set from the CLI. This check only covers the repos themselves: a base branch that’s since been deleted isn’t caught until the spawned task’s sandbox is created.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close