Skip to main content

​
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

Run once at a specific time each day:
{
  "schedule": {
    "kind": "at",
    "at": "06:00"
  }
}

​
Job Types (Payloads)

Sends a system event to the agent’s session:
{
  "kind": "systemEvent",
  "text": "Daily morning briefing: Check tasks, review calendar, report status."
}
Triggers a full agent turn with a prompt, optionally delivering the response to a channel:
{
  "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
}
Plays an audio alert through the dashboard’s TTS system:
{
  "kind": "audioAlert",
  "message": "Time for your afternoon standup review.",
  "title": "Standup Reminder",
  "voice": "Jessica",
  "mood": "professional",
  "urgency": "info"
}
Sends a silent prompt to the agent (no user-visible output):
{
  "kind": "nudge",
  "text": "Check if any execution worker tasks are blocked.",
  "label": "Worker Health Check"
}
Scans Gmail for emails from important contacts:
{
  "kind": "vipEmailScan",
  "emitAlerts": true,
  "maxResults": 10,
  "lookbackDays": 1,
  "accounts": ["[email protected]"]
}
Monitors Slack channels for signals that need agent attention:
{
  "kind": "slackSignalScan",
  "emitAlerts": true,
  "createTasks": true,
  "accountId": "default"
}

​
Session Targets

TargetBehavior
mainRuns in the agent’s main session. Has full context and memory.
isolatedRuns in a fresh isolated session. No prior context. Used for autonomous grunt work.

​
Execution Modes

ModeBehavior
liveFull execution with side effects (messages sent, tasks created)
paper_tradeSimulated execution. Actions are logged but not executed. Used for testing.

​
Wake Modes

ModeBehavior
nowExecute immediately when the schedule fires
next-heartbeatQueue for execution at the next heartbeat cycle

​
CLI Commands

# 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

MethodDescription
cron.listList all jobs (optionally include disabled)
cron.statusGet cron service status
cron.addCreate a new job
cron.updateUpdate an existing job
cron.removeDelete a job
cron.runForce-run a job
cron.runsList recent run history

​
The Minion Pattern

The minion pattern is a cron-driven workflow for autonomous background work. See the dedicated Minion Pattern page for a deep dive.
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

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