Pulse Scheduler

Pulse is DorkOS's cron scheduling system for AI agents. You define schedules with cron expressions and prompts, and Pulse triggers autonomous agent sessions at the specified intervals. Agents run with their own working directory and prompt, producing results you can review in the run history.

Enabling Pulse

Pulse is enabled by default. If it has been disabled, re-enable it:

dorkos --pulse

Creating Schedules

There are three ways to create a Pulse schedule.

PulsePanel UI

Open the Pulse tab and click "Create Schedule". The dialog lets you configure:

• Name -- A human-readable label for the schedule (e.g., "Daily code review")
• Cron expression -- When the job should run (see Cron Syntax below). Choose from preset buttons or build a custom expression with the visual builder.
• 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) -- "Allow file edits" (acceptEdits, default) requires the agent to request approval for file changes. "Full autonomy" (bypassPermissions) lets the agent execute any tool without approval.
• Max runtime (Advanced) -- Maximum execution time in minutes (default: 10, max: 720). The run is cancelled if it exceeds this limit.

REST API

Create a schedule with a POST request:

curl -X POST http://localhost:4242/api/pulse/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 its initial state (active).

MCP Tools

Agents can create schedules using the create_schedule MCP tool. Schedules created by agents enter the pending_approval state and must be approved by a human before they start running.

create_schedule({
  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

Pulse uses standard five-field cron expressions. The PulsePanel includes a CronVisualBuilder component that lets you build expressions visually, and CronPresets for common patterns.

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

Common Presets

The TimezoneCombobox in the create dialog lets you pick a timezone for the schedule. All cron expressions are evaluated in the selected timezone.

Run History

Every schedule execution creates a run record stored in the consolidated SQLite database at ~/.dork/dork.db. The RunHistoryPanel in the Pulse tab shows past runs with their status and timing.

Run States

Click any run in the history to open the full agent conversation in the chat UI. This navigates to the session transcript, where you can see every tool call, response, and output the agent produced during the run.

Managing Runs

You can cancel an active run from the UI or via the API:

# Cancel a running job
curl -X POST http://localhost:4242/api/pulse/runs/{runId}/cancel

You can also manually trigger a schedule outside its cron timing:

# Trigger an immediate run
curl -X POST http://localhost:4242/api/pulse/schedules/{scheduleId}/trigger

Pulse 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) ensures a schedule cannot start a new run if its previous run is still active.

Pulse + Relay

When both Pulse and Relay are enabled, schedule dispatch integrates with the message bus. Instead of calling the AgentManager directly, Pulse publishes to relay.system.pulse.{scheduleId}. The ClaudeCodeAdapter picks up the message and routes it to a new agent session.

This integration provides several benefits:

• 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.
• Adapter routing -- Scheduled messages flow through the same adapter pipeline as all other Relay messages, benefiting from the same reliability mechanisms (circuit breakers, backpressure, dead letter queue).

Configuration

Schedule States

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

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

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

Pulse data (both schedule definitions and run history) is stored in the consolidated SQLite database at ~/.dork/dork.db with WAL mode for concurrent read/write access.

Next Steps