Cron Tool - PicoClaw

The cron tool provides comprehensive scheduling capabilities for agents, supporting one-time reminders, recurring tasks, and automated command execution.

cron

Schedule reminders, tasks, or system commands.

Parameters

action

string

required

Action to perform:

"add" - Create a new scheduled job
"list" - List all scheduled jobs
"remove" - Delete a job
"enable" - Enable a disabled job
"disable" - Temporarily disable a job

For “add” action:

message

string

required

The reminder/task message to display when triggered. If command is used, this describes what the command does.

at_seconds

integer

One-time reminder: seconds from now when to trigger (e.g., 600 for 10 minutes later).Use this for one-time reminders like “remind me in 10 minutes”.

every_seconds

integer

Recurring interval in seconds (e.g., 3600 for every hour).Use this ONLY for recurring tasks like “every 2 hours” or “daily reminder”.

cron_expr

string

Cron expression for complex recurring schedules (e.g., “0 9 * * *” for daily at 9am).Use standard cron syntax: minute hour day month weekday

command

string

Optional: Shell command to execute directly (e.g., “df -h”).If set, the agent will run this command and report output instead of just showing the message. deliver will be forced to false for commands.

deliver

boolean

If true, send message directly to channel. If false, let agent process message for complex tasks. Default: true.

For “remove”, “enable”, “disable” actions:

job_id

string

required

The ID of the job to modify.

Returns

result

string

Confirmation message with job details or list of scheduled jobs.

Usage Examples

One-Time Reminder

{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Check the build status",
    "at_seconds": 600
  }
}

Result: Reminder triggers in 10 minutes (600 seconds).

Recurring Task

{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Hourly system check",
    "every_seconds": 3600
  }
}

Result: Task runs every hour.

Cron Expression

{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Daily backup reminder",
    "cron_expr": "0 9 * * *"
  }
}

Result: Runs daily at 9:00 AM.

Scheduled Command

{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Check disk space",
    "command": "df -h",
    "every_seconds": 3600
  }
}

Result: Executes df -h every hour and reports output.

Schedule Types

One-Time (at_seconds)

Triggers once at a specific time in the future.

{
  "at_seconds": 300   // 5 minutes from now
}

Common values:

60 = 1 minute
300 = 5 minutes
600 = 10 minutes
1800 = 30 minutes
3600 = 1 hour
86400 = 1 day

Internal storage: Converted to absolute timestamp in milliseconds.

Recurring (every_seconds)

Repeats at fixed intervals.

{
  "every_seconds": 7200  // Every 2 hours
}

Common intervals:

60 = Every minute
300 = Every 5 minutes
3600 = Every hour
7200 = Every 2 hours
86400 = Daily
604800 = Weekly

Internal storage: Stored as milliseconds interval.

Cron Expression (cron_expr)

Uses standard cron syntax for complex schedules.

minute hour day month weekday

Examples:

// Daily at 9 AM
{ "cron_expr": "0 9 * * *" }

// Every Monday at 10:30 AM
{ "cron_expr": "30 10 * * 1" }

// Every 15 minutes
{ "cron_expr": "*/15 * * * *" }

// First day of month at midnight
{ "cron_expr": "0 0 1 * *" }

// Weekdays at 5 PM
{ "cron_expr": "0 17 * * 1-5" }

Cron syntax:

* = any value
*/n = every n units
n,m = specific values
n-m = range of values

Delivery Modes

Direct Delivery (deliver=true)

Message is sent directly to the chat channel without agent processing.

{
  "message": "Time for your break!",
  "deliver": true
}

Use for:

Simple reminders
Notifications
Alerts

Agent Processing (deliver=false)

Message is processed by the agent, allowing complex task execution.

{
  "message": "Analyze today's logs and summarize errors",
  "deliver": false
}

Use for:

Tasks requiring agent reasoning
Multi-step operations
Context-aware actions

Command Execution

When command is specified, it executes directly via the exec tool.

{
  "message": "Disk space check",
  "command": "df -h",
  "every_seconds": 3600
}

Behavior:

Executes shell command
Captures output (stdout + stderr)
Reports results to chat
Respects exec tool safety guards

Job Management

List Jobs

{
  "action": "list"
}

Output:

Scheduled jobs:
- Check disk space (id: job-123, every 3600s)
- Daily backup reminder (id: job-456, 0 9 * * *)
- Meeting reminder (id: job-789, one-time)

Remove Job

{
  "action": "remove",
  "job_id": "job-123"
}

Result: "Cron job removed: job-123"

Enable Job

{
  "action": "enable",
  "job_id": "job-123"
}

Result: "Cron job 'Check disk space' enabled"

Disable Job

{
  "action": "disable",
  "job_id": "job-123"
}

Result: "Cron job 'Check disk space' disabled" Disabled jobs are not deleted but won’t execute until re-enabled.

Context Management

Jobs inherit context from the conversation where they’re created:

cronTool.SetContext("telegram", "123456789")

This ensures:

Job messages are sent to the original channel
Job output reaches the correct user
Multi-user agents maintain proper routing

Job Execution

When a job triggers, the cron tool’s ExecuteJob method is called:

Execution Flow

Command jobs: Execute via exec tool → Report output
Direct delivery: Send message to channel immediately
Agent processing: Route message through agent loop

Command Execution

// Executes command and reports output
args := map[string]any{"command": job.Payload.Command}
result := execTool.Execute(ctx, args)

Output format:

Scheduled command 'df -h' executed:
[command output]

Error format:

Error executing scheduled command: [error details]

Timeout Configuration

cronTool := NewCronTool(
    cronService,
    executor,
    msgBus,
    workspace,
    restrict,
    5 * time.Minute,  // Command timeout
    config,
)

Commands timeout after the specified duration.

Error Handling

Missing Parameters

{ "error": "action is required" }
{ "error": "message is required for add" }
{ "error": "job_id is required for remove" }

Invalid Schedule

{
  "error": "one of at_seconds, every_seconds, or cron_expr is required"
}

Missing Context

{
  "error": "no session context (channel/chat_id not set). Use this tool in an active conversation."
}

Job Not Found

{ "error": "Job job-123 not found" }

Add Job Failure

{
  "error": "Error adding job: invalid cron expression"
}

Best Practices

1. Choose the Right Schedule Type

// ✅ Good - One-time reminder
{ "at_seconds": 1800 }

// ❌ Avoid - Recurring with at_seconds
{ "at_seconds": 3600, "every_seconds": 3600 }  // Confusing!

2. Provide Descriptive Messages

// ✅ Good
{ "message": "Daily standup meeting in 5 minutes" }

// ❌ Avoid
{ "message": "reminder" }

3. Use Commands for Simple Operations

// ✅ Good
{ "command": "df -h" }

// ❌ Avoid - Agent processing not needed
{ "message": "Run df -h and show output", "deliver": false }

4. List Jobs Regularly

Prevent accumulation of obsolete jobs:

{ "action": "list" }

5. Use Meaningful Job Names

The first 30 characters of message become the job name:

// ✅ Good
{ "message": "Hourly disk space check - Alert if < 10%" }

// ❌ Avoid
{ "message": "Check" }

Integration Examples

Daily Report

{
  "action": "add",
  "message": "Generate daily activity report",
  "cron_expr": "0 17 * * 1-5",
  "deliver": false
}

System Monitoring

{
  "action": "add",
  "message": "Check system resources",
  "command": "top -bn1 | head -20",
  "every_seconds": 300
}

Meeting Reminders

{
  "action": "add",
  "message": "Team standup in 5 minutes",
  "cron_expr": "25 9 * * 1-5"
}

Backup Verification

{
  "action": "add",
  "message": "Verify last night's backup",
  "command": "ls -lh /backups | tail -5",
  "cron_expr": "0 8 * * *"
}

Tools API

Provider API

​cron

​Parameters

​For “add” action:

​For “remove”, “enable”, “disable” actions:

​Returns

​Usage Examples

​One-Time Reminder

​Recurring Task

​Cron Expression

​Scheduled Command

​Schedule Types

​One-Time (at_seconds)

​Recurring (every_seconds)

​Cron Expression (cron_expr)

​Delivery Modes

​Direct Delivery (deliver=true)

​Agent Processing (deliver=false)

​Command Execution

​Job Management

​List Jobs

​Remove Job

​Enable Job

​Disable Job

​Context Management

​Job Execution

​Execution Flow

​Command Execution

​Timeout Configuration

​Error Handling

​Missing Parameters

​Invalid Schedule

​Missing Context

​Job Not Found

​Add Job Failure

​Best Practices

​1. Choose the Right Schedule Type

​2. Provide Descriptive Messages

​3. Use Commands for Simple Operations

​4. List Jobs Regularly

​5. Use Meaningful Job Names

​Integration Examples

​Daily Report

​System Monitoring

​Meeting Reminders

​Backup Verification

Build docs developers (and LLMs) love

cron

Parameters

For “add” action:

For “remove”, “enable”, “disable” actions:

Returns

Usage Examples

One-Time Reminder

Recurring Task

Cron Expression

Scheduled Command

Schedule Types

One-Time (at_seconds)

Recurring (every_seconds)

Cron Expression (cron_expr)

Delivery Modes

Direct Delivery (deliver=true)

Agent Processing (deliver=false)

Command Execution

Job Management

List Jobs

Remove Job

Enable Job

Disable Job

Context Management

Job Execution

Execution Flow

Command Execution

Timeout Configuration

Error Handling

Missing Parameters

Invalid Schedule

Missing Context

Job Not Found

Add Job Failure

Best Practices

1. Choose the Right Schedule Type

2. Provide Descriptive Messages

3. Use Commands for Simple Operations

4. List Jobs Regularly

5. Use Meaningful Job Names

Integration Examples

Daily Report

System Monitoring

Meeting Reminders

Backup Verification