Scheduled Tasks (Cron)

PicoClaw’s cron tool allows the agent to schedule reminders, recurring tasks, and automated commands. This is perfect for time-based reminders, periodic checks, and scheduled automation.

Overview

The cron system supports:

One-time reminders - “Remind me in 10 minutes”
Recurring tasks - “Remind me every 2 hours”
Complex schedules - “Remind me at 9am daily” (cron expressions)
Command execution - Run shell commands on schedule

Tool Usage

The agent uses the cron tool automatically when you ask for reminders or scheduled tasks.

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Action to perform: `add`, `list`, `remove`, `enable`, `disable`
`message`	string	For add	The reminder/task message to display
`command`	string	Optional	Shell command to execute
`at_seconds`	integer	Optional	One-time: seconds from now (e.g., 600 for 10 minutes)
`every_seconds`	integer	Optional	Recurring: interval in seconds (e.g., 3600 for hourly)
`cron_expr`	string	Optional	Cron expression for complex schedules
`job_id`	string	For remove/enable/disable	Job ID to operate on
`deliver`	boolean	Optional	If true, send message directly; if false, let agent process (default: true)

Usage Examples

One-time Reminders

User: “Remind me in 10 minutes to check the server” Agent calls:

{
  "action": "add",
  "message": "Check the server",
  "at_seconds": 600
}

User: “Remind me in 1 hour to start the meeting” Agent calls:

{
  "action": "add",
  "message": "Start the meeting",
  "at_seconds": 3600
}

Recurring Tasks

User: “Remind me every 2 hours to take a break” Agent calls:

{
  "action": "add",
  "message": "Take a break",
  "every_seconds": 7200
}

User: “Check disk space every 30 minutes” Agent calls:

{
  "action": "add",
  "message": "Check disk space",
  "every_seconds": 1800
}

Cron Expressions

User: “Remind me to review emails at 9am every weekday” Agent calls:

{
  "action": "add",
  "message": "Review emails",
  "cron_expr": "0 9 * * 1-5"
}

User: “Run backup at midnight daily” Agent calls:

{
  "action": "add",  
  "message": "Daily backup",
  "cron_expr": "0 0 * * *"
}

Command Execution

User: “Check disk usage every hour” Agent calls:

{
  "action": "add",
  "message": "Check disk usage",
  "command": "df -h",
  "every_seconds": 3600
}

When triggered, the agent executes df -h and reports output.

Managing Jobs

List all jobs:

picoclaw agent -m "List all my reminders"

Agent calls:

{
  "action": "list"
}

Remove a job:

picoclaw agent -m "Remove the disk space check"

Agent calls:

{
  "action": "remove",
  "job_id": "abc123"
}

Disable a job:

picoclaw agent -m "Disable the hourly reminder"

Agent calls:

{
  "action": "disable",
  "job_id": "xyz789"
}

Cron Expression Format

Cron expressions use the standard 5-field format:

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

Common Examples

Expression	Description
`0 9 * * *`	Daily at 9:00 AM
`0 /2 * *`	Every 2 hours
`30 8 * * 1-5`	Weekdays at 8:30 AM
`0 0 1 * *`	First day of each month at midnight
`0 12 * * 6`	Every Saturday at noon
`/15 * * *`	Every 15 minutes
`0 0,12 * * *`	Twice a day (midnight and noon)
`0 9 * * 1`	Every Monday at 9 AM

Special Characters

* - Any value
, - Value list (e.g., 1,15 for 1st and 15th)
- - Range (e.g., 1-5 for Monday-Friday)
/ - Step values (e.g., */15 for every 15 minutes)

CLI Commands

You can also manage cron jobs via CLI:

List Jobs

picoclaw cron list

Output:

Scheduled jobs:
- Check disk usage (id: abc123, every 3600s)
- Daily backup (id: def456, cron: 0 0 * * *)
- Meeting reminder (id: ghi789, one-time)

Add Job via CLI

# One-time reminder
picoclaw cron add "Take a break" --at 600

# Recurring task
picoclaw cron add "Check server" --every 3600

# Cron expression
picoclaw cron add "Daily report" --cron "0 9 * * *"

Storage

Cron jobs are stored in your workspace:

~/.picoclaw/workspace/cron/
├── jobs.json         # Job definitions
└── state.json        # Execution state

Job Format

{
  "id": "abc123",
  "name": "Check disk usage",
  "schedule": {
    "kind": "every",
    "every_ms": 3600000
  },
  "payload": {
    "message": "Check disk usage",
    "command": "df -h",
    "deliver": false,
    "channel": "telegram",
    "to": "123456789"
  },
  "enabled": true,
  "created_at": 1709856000000
}

Configuration

Configure execution timeout in ~/.picoclaw/config.json:

{
  "tools": {
    "cron": {
      "exec_timeout_minutes": 5
    }
  }
}

Options

Option	Type	Default	Description
`exec_timeout_minutes`	integer	`5`	Command execution timeout (0 = no timeout)

How It Works

Schedule Types

The cron service supports three schedule types:

1. At (One-time)

Triggers once at a specific Unix timestamp:

{
  "kind": "at",
  "at_ms": 1709856000000
}

2. Every (Recurring Interval)

Triggers at regular intervals:

{
  "kind": "every",
  "every_ms": 3600000
}

3. Cron (Expression-based)

Triggers based on cron expression:

{
  "kind": "cron",
  "expr": "0 9 * * *"
}

Execution Flow

Schedule triggers
    ↓
Cron service calls CronTool.ExecuteJob()
    ↓
Check payload type:
├─ Command? → Execute via exec tool → Report output
├─ Deliver=true? → Send message directly to channel
└─ Deliver=false? → Process through agent → Agent responds

Command Execution

When a job has a command field:

Command executed via ExecTool (respects workspace restrictions)
Output captured
Result sent to channel/chat specified in job
Execution timeout enforced (default: 5 minutes)

Delivery Modes

Direct delivery (deliver: true):

Message sent directly to channel
No agent processing
Fast and simple

Agent processing (deliver: false):

Message processed by agent
Agent can use tools, access context
For complex tasks requiring decision-making

Session Context

When creating jobs, the cron tool captures current session context:

Channel: Where the job was created (telegram, discord, cli, etc.)
Chat ID: Which chat/user requested the job

This ensures notifications go to the right place:

User (Telegram: 123456789): "Remind me in 1 hour"
                                ↓
                  Job created with context:
                  - channel: telegram
                  - chat_id: 123456789
                                ↓
                  1 hour later → Reminder sent to:
                  - Telegram chat 123456789 ✅

Best Practices

Choosing Schedule Type

✅ Use at_seconds for:

One-time reminders
Temporary schedules
Countdown timers

✅ Use every_seconds for:

Simple recurring tasks
Regular intervals
Monitoring checks

✅ Use cron_expr for:

Specific times (“9am daily”)
Complex schedules (“weekdays only”)
Calendar-based triggers

Performance Considerations

Avoid very frequent jobs (< 1 minute intervals)
Use deliver: true for simple notifications
Keep command execution under timeout limit
Consider using heartbeat for background tasks instead

Security

Commands execute with same restrictions as agent:

Respects restrict_to_workspace setting
Blocked dangerous commands (rm -rf, etc.)
Timeout enforcement prevents runaway processes

Troubleshooting

Job Not Triggering

Check job is enabled:

picoclaw cron list

Verify schedule:
- For at_seconds: Check time is in future
- For every_seconds: Ensure interval is reasonable
- For cron_expr: Validate expression format
Check logs:

picoclaw gateway 2>&1 | grep cron

Command Not Executing

Verify command field is set:
- Commands must have command field in payload
- deliver is automatically set to false for commands
Check timeout:
- Default: 5 minutes
- Increase if command takes longer
Verify workspace restrictions:
- Command paths must be within workspace if restricted
- Check restrict_to_workspace setting

Wrong Delivery Channel

Check session context:
- Jobs remember channel/chat where created
- Create new job from correct channel
Manual override:
- Edit job file manually if needed
- Located in ~/.picoclaw/workspace/cron/

Differences from Heartbeat

Feature	Cron	Heartbeat
Trigger	Time-based schedules	Fixed interval
Configuration	Dynamic via tool calls	Static HEARTBEAT.md file
Use Case	Specific reminders & tasks	Background monitoring
Precision	Exact times/intervals	Approximate interval
Management	Add/remove via commands	Edit markdown file

Choose cron for:

Specific time-based reminders
One-time notifications
User-requested schedules

Choose heartbeat for:

Continuous background monitoring
Regular health checks
Automated maintenance tasks

Heartbeat - Periodic background tasks
Spawn Tool - Async subagent execution
Exec Tool - Command execution

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

Documentation Index

​Overview

​Tool Usage

​Parameters

​Usage Examples

​One-time Reminders

​Recurring Tasks

​Cron Expressions

​Command Execution

​Managing Jobs

​Cron Expression Format

​Common Examples

​Special Characters

​CLI Commands

​List Jobs

​Add Job via CLI

​Storage

​Job Format

​Configuration

​Options

​How It Works

​Schedule Types

​1. At (One-time)

​2. Every (Recurring Interval)

​3. Cron (Expression-based)

​Execution Flow

​Command Execution

​Delivery Modes

​Session Context

​Best Practices

​Choosing Schedule Type

​Performance Considerations

​Security

​Troubleshooting

​Job Not Triggering

​Command Not Executing

​Wrong Delivery Channel

​Differences from Heartbeat

​Related Features

Build docs developers (and LLMs) love

Overview

Tool Usage

Parameters

Usage Examples

One-time Reminders

Recurring Tasks

Cron Expressions

Command Execution

Managing Jobs

Cron Expression Format

Common Examples

Special Characters

CLI Commands

List Jobs

Add Job via CLI

Storage

Job Format

Configuration

Options

How It Works

Schedule Types

1. At (One-time)

2. Every (Recurring Interval)

3. Cron (Expression-based)

Execution Flow

Command Execution

Delivery Modes

Session Context

Best Practices

Choosing Schedule Type

Performance Considerations

Security

Troubleshooting

Job Not Triggering

Command Not Executing

Wrong Delivery Channel

Differences from Heartbeat

Related Features