> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron & Scheduled Jobs

> Scheduled job system for ArgentOS — periodic agent tasks, automated scans, nudges, and the minion pattern for autonomous background work.

## Overview

The ArgentOS cron system enables scheduled, repeating, and one-shot jobs that run agent actions at specified times or intervals. Jobs can trigger system events, agent turns, audio alerts, nudges, email scans, and Slack signal scans.

Unlike traditional cron (which runs shell commands), ArgentOS cron jobs interact with the agent runtime. A job might prompt the agent to generate a daily intel brief, scan for VIP emails, or run a periodic health check.

## Schedule Types

<Tabs>
  <Tab title="Fixed Time (at)">
    Run once at a specific time each day:

    ```json theme={null}
    {
      "schedule": {
        "kind": "at",
        "at": "06:00"
      }
    }
    ```
  </Tab>

  <Tab title="Interval (every)">
    Run at a fixed interval in milliseconds:

    ```json theme={null}
    {
      "schedule": {
        "kind": "every",
        "everyMs": 1800000,
        "anchorMs": 1711000000000
      }
    }
    ```

    The optional `anchorMs` provides a reference timestamp so intervals stay consistent across restarts.
  </Tab>

  <Tab title="Cron Expression">
    Standard cron expressions with optional timezone:

    ```json theme={null}
    {
      "schedule": {
        "kind": "cron",
        "expr": "0 6 * * 1-5",
        "tz": "America/Chicago"
      }
    }
    ```
  </Tab>
</Tabs>

## Job Types (Payloads)

<AccordionGroup>
  <Accordion title="System Event">
    Sends a system event to the agent's session:

    ```json theme={null}
    {
      "kind": "systemEvent",
      "text": "Daily morning briefing: Check tasks, review calendar, report status."
    }
    ```
  </Accordion>

  <Accordion title="Agent Turn">
    Triggers a full agent turn with a prompt, optionally delivering the response to a channel:

    ```json theme={null}
    {
      "kind": "agentTurn",
      "message": "Generate the daily AI intelligence briefing.",
      "model": "anthropic/claude-sonnet-4-20250514",
      "thinking": "medium",
      "timeoutSeconds": 300,
      "deliver": true,
      "channel": "telegram",
      "to": "user:123456",
      "bestEffortDeliver": true
    }
    ```
  </Accordion>

  <Accordion title="Audio Alert">
    Plays an audio alert through the dashboard's TTS system:

    ```json theme={null}
    {
      "kind": "audioAlert",
      "message": "Time for your afternoon standup review.",
      "title": "Standup Reminder",
      "voice": "Jessica",
      "mood": "professional",
      "urgency": "info"
    }
    ```
  </Accordion>

  <Accordion title="Nudge">
    Sends a silent prompt to the agent (no user-visible output):

    ```json theme={null}
    {
      "kind": "nudge",
      "text": "Check if any execution worker tasks are blocked.",
      "label": "Worker Health Check"
    }
    ```
  </Accordion>

  <Accordion title="VIP Email Scan">
    Scans Gmail for emails from important contacts:

    ```json theme={null}
    {
      "kind": "vipEmailScan",
      "emitAlerts": true,
      "maxResults": 10,
      "lookbackDays": 1,
      "accounts": ["work@example.com"]
    }
    ```
  </Accordion>

  <Accordion title="Slack Signal Scan">
    Monitors Slack channels for signals that need agent attention:

    ```json theme={null}
    {
      "kind": "slackSignalScan",
      "emitAlerts": true,
      "createTasks": true,
      "accountId": "default"
    }
    ```
  </Accordion>
</AccordionGroup>

## Session Targets

| Target     | Behavior                                                                            |
| ---------- | ----------------------------------------------------------------------------------- |
| `main`     | Runs in the agent's main session. Has full context and memory.                      |
| `isolated` | Runs in a fresh isolated session. No prior context. Used for autonomous grunt work. |

## Execution Modes

| Mode          | Behavior                                                                    |
| ------------- | --------------------------------------------------------------------------- |
| `live`        | Full execution with side effects (messages sent, tasks created)             |
| `paper_trade` | Simulated execution. Actions are logged but not executed. Used for testing. |

## Wake Modes

| Mode             | Behavior                                        |
| ---------------- | ----------------------------------------------- |
| `now`            | Execute immediately when the schedule fires     |
| `next-heartbeat` | Queue for execution at the next heartbeat cycle |

## CLI Commands

```bash theme={null}
# List all jobs
argent cron list

# Add a job (interactive wizard)
argent cron add

# Force-run a job immediately
argent cron trigger <job-id>

# Delete a job
argent cron remove <job-id>
```

## Gateway API

| Method        | Description                                 |
| ------------- | ------------------------------------------- |
| `cron.list`   | List all jobs (optionally include disabled) |
| `cron.status` | Get cron service status                     |
| `cron.add`    | Create a new job                            |
| `cron.update` | Update an existing job                      |
| `cron.remove` | Delete a job                                |
| `cron.run`    | Force-run a job                             |
| `cron.runs`   | List recent run history                     |

## The Minion Pattern

<Tip>
  The minion pattern is a cron-driven workflow for autonomous background work. See the dedicated [Minion Pattern](/agents/minion-pattern) page for a deep dive.
</Tip>

An isolated cron session does grunt work (research, drafting, analysis), then hands off the result to the main session for delivery:

1. **Cron job fires** with `sessionTarget: "isolated"` and an `agentTurn` payload
2. **Isolated session** runs without prior context, does research using tools
3. **Isolated session writes output** to the doc panel and creates a handoff task
4. **Main session picks up** the handoff task during its next heartbeat
5. **Main session adds personality** -- memory context, relationship awareness -- and delivers the final output

## Configuration

```json theme={null}
{
  "cron": {
    "enabled": true,
    "store": "~/.argentos/cron-jobs.json",
    "maxConcurrentRuns": 2
  }
}
```