Recurring Tasks

Recurring Tasks let you schedule a workflow to execute automatically on a repeating schedule. Instead of manually triggering a run each morning for a nightly code quality check or each Monday for a dependency update, you define a recurring task once and CodeCourier fires it automatically at the configured frequency. Each firing creates a standard workflow run with source scheduled, which appears in your project’s run history like any other run.

Recurring Task Data Model

A recurring task record contains all the information needed to schedule and configure each run it fires:

{
  title: string,                        // Human-readable name for the task
  description: string,                  // Optional longer description
  prompt: string,                       // The prompt sent to the workflow each firing
  frequency: "daily"                    // How often the task fires
            | "every_other_day"
            | "weekly"
            | "biweekly"
            | "monthly",
  targetWorkflowId: string,             // Workflow blueprint to execute
  projectId: string,                    // Owning project
  createdBy: string,                    // User who created the task
  isActive: boolean,                    // Whether the task is currently enabled
  timezone: string,                     // IANA timezone (e.g., "America/New_York")
  scheduledHour: number,               // Hour to fire (0-23, in the given timezone)
  scheduledMinute: number,             // Minute to fire (0-59)
  nextRunAt: number,                    // Unix timestamp of next scheduled execution
}

Frequency Options

CodeCourier supports five recurrence frequencies:

• daily - Fires once every calendar day at the configured hour and minute. Use for nightly quality checks, daily test runs, or continuous dependency scanning.
• every_other_day - Fires every two days. A lighter cadence than daily - useful for tasks that are important but do not need to run every single day.
• weekly - Fires once per week on the same day and time as the original creation. Use for weekly dependency updates, weekly refactoring sweeps, or weekly coverage reports.
• biweekly - Fires every two weeks. Suitable for tasks with a sprint cadence, such as security audits or documentation updates aligned to development cycles.
• monthly - Fires once per calendar month. Best for infrequent, high-impact automation such as major dependency upgrades or compliance checks.

Creating a Recurring Task

Recurring tasks are created from the project’s recurring tasks section, accessible at /p/[id]/recurring. Each task can also be viewed and edited individually at /p/[id]/recurring/[taskId].

How Scheduled Runs Work

When a recurring task fires, the CodeCourier scheduler creates a workflow run with additional scheduling metadata:

{
  source: "scheduled",                  // Identifies the run as scheduler-originated
  workflowId: task.targetWorkflowId,
  prompt: task.prompt,
  scheduledFor: timestamp,              // When the task was scheduled to fire
  timezone: task.timezone,              // Timezone from the recurring task
  recurrencePattern: task.frequency,    // e.g., "daily", "weekly"
  recurringTaskId: task._id,            // Reference back to the recurring task
  // ... standard run configuration
}

These fields appear in the run detail view, linking each execution back to the recurring task that triggered it. The scheduledFor timestamp reflects the intended fire time, which may differ slightly from the actual startedAt time due to scheduler queue latency.

Runs List Integration

Scheduled runs appear in the project’s Runs list with:

• Source badge showing scheduled (distinct fromworkflow, sprint, or sandbox).
• The recurring task’s title as part of the run name, making scheduled runs easy to identify at a glance.
• Standard status tracking - scheduled runs transition through the same pending → running → completed/failed lifecycle as all other runs.

Managing Recurring Tasks

Activating and Deactivating

Every recurring task has an isActive toggle. Deactivating a task suspends all future firings without deleting the task. The nextRunAt field is cleared when a task is deactivated. Reactivating the task recalculates nextRunAt from the current time forward based on the frequency and schedule.

Editing a Recurring Task

All fields of a recurring task can be edited from its detail page. Changes take effect for the next firing - any run currently in progress uses the configuration from when it was triggered, not the updated values. Editing the schedule (frequency, timezone, hour, or minute) causes CodeCourier to recompute nextRunAt immediately.

You can change:

• Title and description.
• Prompt - the updated prompt is used from the next firing onward.
• Target workflow - swap in a different pipeline for future runs.
• Frequency, timezone, hour, and minute.

Deleting a Recurring Task

Deleting a recurring task removes it permanently and stops all future firings. Runs that were created by the task remain in the run history and are not affected. To preserve the task configuration for potential future use, consider deactivating rather than deleting.

Timezone Handling

Recurring tasks store an explicit IANA timezone so that schedules behave intuitively regardless of where team members are located or what server timezone CodeCourier runs on. The timezone is applied to both the initial nextRunAt computation and to every subsequent recurrence calculation after a task fires.

Daylight saving time transitions are handled automatically. A task configured to fire at 09:00 America/New_York fires at 9:00 AM Eastern Time year-round, adjusting for EST/EDT transitions without manual intervention.

Viewing Run History for a Task

The recurring task detail page (/p/[id]/recurring/[taskId]) shows the run history for that specific task - all runs with a matching recurringTaskId. This gives you a focused view of how the scheduled workflow has been performing over time: how many runs succeeded, how many failed, and any patterns in execution duration or quality scores.

From each run entry in the task history, you can navigate to the full run detail page to inspect sandbox output, step verdicts, PR URLs, and quality scores.

Use Cases

• Nightly code quality checks - A daily task runs a quality workflow every night at 2:00 AM, catching type errors, lint violations, and test failures introduced during the day.
• Weekly dependency updates - A weekly task fires every Monday and runs a workflow that audits npm dependencies, updates outdated packages, and opens a PR with the changes.
• Daily test runs - A daily task executes a workflow that compiles the project and runs the full test suite, reporting failures via the run notification system.
• Biweekly security audits - A biweekly task triggers a deep-dive workflow that scans for common vulnerabilities in dependencies, configuration, and code patterns.
• Monthly documentation sync - A monthly task runs a designer workflow that reads the codebase and updates API documentation to reflect changes made over the past month.
• Continuous performance baseline - An every-other-day task runs a workflow that executes performance benchmarks and commits the results, building a long-term baseline for regression detection.