---
title: "Issue schedules"
canonical: https://workspace.socra.com/docs/cortex/guides/issue-schedules
---

# Issue schedules

An Issue schedule creates ordinary Cortex Issues from a recurring template. Use one for repeated work that should enter the same Module with a consistent title, description, priority, and assignee.

## Before you create a schedule

The examples use the [Socra CLI with Cortex installed](/docs/cortex/reference/cli). You need edit access to the active Module that will own the generated Issues.

The recurrence is a five-field cron expression in this order: minute, hour, day of month, month, and day of week. Supply an IANA time zone such as `America/Chicago`. Cortex uses `UTC` when you omit the time zone.

The template does not include [Issue dependencies](/docs/cortex/concepts/issues-and-coordination#dependencies) or [labels](/docs/cortex/guides/issue-labels#apply-labels-to-issues). Add those fields to a generated Issue when a specific occurrence needs them.

## Create a schedule

Replace `MODULE_NAME` with the name of the owning Module. Create a schedule for Monday at 9:00 AM in Chicago:

```bash
socra cortex issue-schedule create \
  --module MODULE_NAME \
  --title "Weekly queue review" \
  --description "Review released work and record the routing decisions." \
  --cron "0 9 * * 1" \
  --timezone America/Chicago
```

The schedule starts enabled. The command prints its `ischedule_...` ID and next run time. Use that ID as `SCHEDULE_ID` in later commands.

Add `--priority` when every generated Issue needs the same priority. Add `--assignee` with a directory handle or Account user ID to route each Issue explicitly. An unassigned generated Issue follows the normal [inbox routing order](/docs/cortex/concepts/inbox#when-an-issue-appears).

## Choose run policies

Two policies control what happens when scheduled work accumulates.

| Setting         | Value       | Behavior                                                                                                                |
| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--overlap`     | `coalesce`  | Default. Cortex does not create another Issue while an earlier Issue from the schedule remains `open` or `in_progress`. |
| `--overlap`     | `allow`     | Cortex can create a new Issue while an earlier generated Issue remains active.                                          |
| `--missed-runs` | `next_only` | Default. Cortex handles one due occurrence, then moves the clock to the next future occurrence.                         |
| `--missed-runs` | `catch_up`  | Cortex processes overdue occurrences in bounded batches when the enabled schedule fell behind.                          |

Set either policy during creation or update it later. For example:

```bash
socra cortex issue-schedule update SCHEDULE_ID --overlap allow --missed-runs catch_up
```

The overlap policy still applies during catch-up. With `coalesce`, an active generated Issue can cause later overdue occurrences to coalesce without creating more Issues.

## Inspect schedules and generated Issues

List a page of schedules you can read:

```bash
socra cortex issue-schedule list
```

Use `--module MODULE_NAME`, `--enabled`, or `--paused` to narrow the list. The options `--enabled` and `--paused` cannot be used together. If more results exist, the CLI prints an `--after` cursor for the next page.

Read one schedule and its next run:

```bash
socra cortex issue-schedule get SCHEDULE_ID
```

Confirm the state, cron expression, time zone, and next run match your intent. The CLI prints run times in UTC, even when the recurrence uses another time zone.

Each generated Issue records the schedule ID and the scheduled occurrence time. It follows the normal [Issue lifecycle](/docs/cortex/concepts/issues-and-coordination), [inbox rules](/docs/cortex/concepts/inbox), access checks, and timeline behavior. Changes to a schedule affect later Issues only.

## Change the template or recurrence

Update only the fields you supply:

```bash
socra cortex issue-schedule update SCHEDULE_ID --cron "0 10 * * 1" --timezone America/Chicago
```

Changing the cron expression or time zone recalculates the next run when the schedule is enabled. You can also update the title, description, priority, assignee, overlap policy, or missed-run policy. Use `--priority none` or `--remove-assignee` to clear those optional fields.

## Pause and resume

Pause the creation of future Issues:

```bash
socra cortex issue-schedule pause SCHEDULE_ID
```

An enabled schedule prevents Cortex from archiving its owning Module. Pause or delete the schedule before you archive that Module.

Resume the schedule when you want new Issues again:

```bash
socra cortex issue-schedule resume SCHEDULE_ID
```

Resume calculates the next future occurrence from the current time. Cortex does not create Issues for occurrences that passed while the schedule was paused.

## Queue an immediate run

If the schedule is paused, resume it first. Queue the enabled schedule for processing:

```bash
socra cortex issue-schedule run SCHEDULE_ID
```

The command queues the run and returns before Cortex processes it. Cortex then applies the overlap policy and advances the schedule to its next occurrence. With `coalesce`, an earlier active Issue prevents a new Issue from being created.

## Delete a schedule

Deletion stops future runs and removes the schedule from normal schedule views. Cortex has no restore command. Issues already created by the schedule remain unchanged.

Delete the schedule:

```bash
socra cortex issue-schedule delete SCHEDULE_ID
```

If Cortex is currently processing a run, deletion is refused. Retry after that run finishes.

## API availability

Issue schedules are available through the Socra CLI and the [Cortex API](/docs/cortex/reference/api). The hosted Cortex MCP server does not currently expose schedule tools. An MCP-only agent must use another authorized interface to manage schedules.