> ## Documentation Index
> Fetch the complete documentation index at: https://sipeed-picoclaw-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron Tool

> Schedule reminders, tasks, and commands with flexible timing options

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

```json theme={null}
{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Check the build status",
    "at_seconds": 600
  }
}
```

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

### Recurring Task

```json theme={null}
{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Hourly system check",
    "every_seconds": 3600
  }
}
```

**Result:** Task runs every hour.

### Cron Expression

```json theme={null}
{
  "tool": "cron",
  "parameters": {
    "action": "add",
    "message": "Daily backup reminder",
    "cron_expr": "0 9 * * *"
  }
}
```

**Result:** Runs daily at 9:00 AM.

### Scheduled Command

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:**

```json theme={null}
// 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "action": "remove",
  "job_id": "job-123"
}
```

**Result:** `"Cron job removed: job-123"`

### Enable Job

```json theme={null}
{
  "action": "enable",
  "job_id": "job-123"
}
```

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

### Disable Job

```json theme={null}
{
  "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:

```go theme={null}
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

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

### Command Execution

```go theme={null}
// 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

```go theme={null}
cronTool := NewCronTool(
    cronService,
    executor,
    msgBus,
    workspace,
    restrict,
    5 * time.Minute,  // Command timeout
    config,
)
```

Commands timeout after the specified duration.

***

## Error Handling

### Missing Parameters

```json theme={null}
{ "error": "action is required" }
{ "error": "message is required for add" }
{ "error": "job_id is required for remove" }
```

### Invalid Schedule

```json theme={null}
{
  "error": "one of at_seconds, every_seconds, or cron_expr is required"
}
```

### Missing Context

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

### Job Not Found

```json theme={null}
{ "error": "Job job-123 not found" }
```

### Add Job Failure

```json theme={null}
{
  "error": "Error adding job: invalid cron expression"
}
```

***

## Best Practices

### 1. Choose the Right Schedule Type

```json theme={null}
// ✅ Good - One-time reminder
{ "at_seconds": 1800 }

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

### 2. Provide Descriptive Messages

```json theme={null}
// ✅ Good
{ "message": "Daily standup meeting in 5 minutes" }

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

### 3. Use Commands for Simple Operations

```json theme={null}
// ✅ 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:

```json theme={null}
{ "action": "list" }
```

### 5. Use Meaningful Job Names

The first 30 characters of `message` become the job name:

```json theme={null}
// ✅ Good
{ "message": "Hourly disk space check - Alert if < 10%" }

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

***

## Integration Examples

### Daily Report

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

### System Monitoring

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

### Meeting Reminders

```json theme={null}
{
  "action": "add",
  "message": "Team standup in 5 minutes",
  "cron_expr": "25 9 * * 1-5"
}
```

### Backup Verification

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.