Task Scheduler

Tasks is DorkOS's cron scheduling engine for AI agents. Define schedules with cron expressions and prompts, and Tasks triggers autonomous agent sessions at the specified intervals — independent of your IDE or terminal. Agents run with their own working directory and prompt, producing results you can review in the run history.

Enabling Tasks

Tasks is feature-flag-guarded. Enable it with the environment variable or CLI flag:

dorkos --tasks

dorkos --no-tasks
# or
export DORKOS_TASKS_ENABLED=false

Preset Gallery

When you have no schedules yet, the Tasks panel shows a Preset Gallery instead of an empty state. Presets are curated schedule templates — common patterns like "Daily standup summary" or "Weekly dependency check" with pre-filled cron expressions and prompts.

Click any preset card to open CreateScheduleDialog pre-populated with that preset's cron expression and prompt. You can edit any field before saving. Presets are read-only suggestions; the final schedule is always yours to customize.

Presets are fetched from the server via GET /api/tasks/presets and cached client-side.

Creating Schedules

TasksPanel UI

Open the Tasks tab and click "Create Schedule" (or select a preset from the gallery). Configure:

• Name — A human-readable label (e.g., "Daily code review")
• Cron expression — When the job runs. Choose from preset buttons or build with the visual editor.
• Prompt — The instruction sent to the agent when the job triggers
• Working directory — The directory the agent operates in
• Timezone — The timezone for the cron expression (defaults to your system timezone)
• Permission mode (Advanced) — acceptEdits requires approval for file changes. bypassPermissions lets the agent execute any tool without approval.
• Max runtime (Advanced) — Maximum execution time in minutes (default: 10, max: 720)

REST API

curl -X POST http://localhost:4242/api/tasks/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily dependency check",
    "cron": "0 9 * * *",
    "prompt": "Check for outdated npm dependencies and create a summary of what needs updating.",
    "cwd": "/home/user/projects/my-app",
    "timezone": "America/New_York"
  }'

The response includes the schedule ID and initial state (active).

MCP Tools

Agents can create schedules using the tasks_create MCP tool. Schedules created by agents enter the pending_approval state and require human approval before they start running.

tasks_create({
  name: "Nightly test suite",
  cron: "0 2 * * *",
  prompt: "Run the full test suite and report any failures.",
  cwd: "/home/user/projects/my-app"
})

Cron Syntax

Tasks uses standard five-field cron expressions. The TasksPanel includes a visual builder and common presets.

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common Presets

Run History

Every schedule execution creates a run record in SQLite. The RunHistoryPanel in the Tasks tab shows past runs with status and timing.

Run States

Click any run in the history to open the full agent conversation. This navigates to the session transcript — every tool call, response, and output the agent produced during the run.

Managing Runs

Cancel an active run:

curl -X POST http://localhost:4242/api/tasks/runs/{runId}/cancel

Trigger a schedule outside its cron timing:

curl -X POST http://localhost:4242/api/tasks/schedules/{scheduleId}/trigger

Tasks enforces a configurable concurrency cap on simultaneous runs. If the cap is reached, new triggers are skipped with a warning log. Overrun protection (via croner's protect option) prevents a schedule from starting a new run if its previous run is still active.

Tasks + Relay

When both Tasks and Relay are enabled, schedule dispatch goes through Relay. Instead of calling the agent runtime directly, Tasks publishes to relay.system.tasks.{scheduleId}. The ClaudeCodeAdapter picks up the message and routes it to a new agent session.

This integration provides:

• Message tracing — Every scheduled run gets a Relay trace ID, so you can track the full delivery path from schedule trigger through agent execution.
• Unified metrics — Scheduled run deliveries appear in the Relay delivery metrics dashboard alongside interactive session messages.
• Reliability — Scheduled messages flow through the same pipeline as all other Relay messages — circuit breakers, backpressure, dead letter queue.

Configuration

Schedule States

Pause and resume schedules from the TasksPanel UI or via PATCH requests:

# Pause a schedule
curl -X PATCH http://localhost:4242/api/tasks/schedules/{scheduleId} \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

# Resume a schedule
curl -X PATCH http://localhost:4242/api/tasks/schedules/{scheduleId} \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Tasks data — schedule definitions and run history — is stored in SQLite at ~/.dork/dork.db with WAL mode for concurrent read/write access.

Next Steps