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

# nullclaw cron

> Schedule and manage periodic tasks

The `nullclaw cron` command manages scheduled tasks that run periodically in the background. Tasks are defined with cron expressions and can execute any agent prompt.

## Subcommands

```bash theme={null}
nullclaw cron list              # List all scheduled tasks
nullclaw cron add               # Add a new task (interactive)
nullclaw cron remove <id>       # Remove a task
nullclaw cron pause <id>        # Pause a task
nullclaw cron resume <id>       # Resume a paused task
nullclaw cron run <id>          # Run a task immediately
```

## cron list

List all scheduled tasks:

```bash theme={null}
nullclaw cron list
```

### Example Output

```
Scheduled Tasks:

ID: backup_memories
Schedule: 0 2 * * * (Daily at 2:00 AM)
Status: active
Prompt: Create a backup of all memories
Last run: 2024-03-01 02:00:00
Next run: 2024-03-02 02:00:00

ID: daily_summary
Schedule: 0 18 * * * (Daily at 6:00 PM)
Status: active
Prompt: Summarize today's conversations and store key insights
Last run: 2024-03-01 18:00:00
Next run: 2024-03-01 18:00:00

ID: weather_check
Schedule: 0 7 * * 1-5 (Weekdays at 7:00 AM)
Status: paused
Prompt: Check weather and send summary via Telegram
Last run: never
Next run: -
```

## cron add

Add a new scheduled task interactively:

```bash theme={null}
nullclaw cron add
```

You'll be prompted for:

1. **Task ID**: Unique identifier (e.g., `daily_backup`)
2. **Cron expression**: Schedule (e.g., `0 2 * * *`)
3. **Prompt**: Agent message to execute
4. **Enabled**: Start active or paused

### Example

```bash theme={null}
$ nullclaw cron add
Task ID: morning_brief
Cron expression: 0 8 * * 1-5
Prompt: Good morning! What's on my schedule today?
Start enabled? [Y/n]: y

Task created: morning_brief
Next run: 2024-03-04 08:00:00
```

## cron remove

Remove a scheduled task:

```bash theme={null}
nullclaw cron remove morning_brief
```

## cron pause / resume

Pause a task without removing it:

```bash theme={null}
# Pause
nullclaw cron pause morning_brief

# Resume
nullclaw cron resume morning_brief
```

## cron run

Run a task immediately (outside its schedule):

```bash theme={null}
nullclaw cron run morning_brief
```

Useful for testing new tasks before committing to a schedule.

## Cron Expression Format

NullClaw uses standard cron syntax:

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

### Examples

| Expression        | Description                                 |
| ----------------- | ------------------------------------------- |
| `0 2 * * *`       | Daily at 2:00 AM                            |
| `*/15 * * * *`    | Every 15 minutes                            |
| `0 9-17 * * 1-5`  | Every hour from 9 AM to 5 PM, weekdays only |
| `0 0 1 * *`       | First day of every month at midnight        |
| `0 8,12,18 * * *` | At 8 AM, 12 PM, and 6 PM daily              |

## Task Storage

Tasks are stored in `~/.nullclaw/cron.json`:

```json theme={null}
{
  "tasks": [
    {
      "id": "morning_brief",
      "schedule": "0 8 * * 1-5",
      "prompt": "Good morning! What's on my schedule?",
      "enabled": true,
      "last_run": null,
      "next_run": "2024-03-04T08:00:00Z"
    }
  ]
}
```

## Use Cases

### Daily Memory Backup

```bash theme={null}
nullclaw cron add
# ID: backup_memories
# Schedule: 0 2 * * *
# Prompt: Export all memories to ~/.nullclaw/backups/
```

### Periodic Summaries

```bash theme={null}
nullclaw cron add
# ID: weekly_summary
# Schedule: 0 18 * * 5
# Prompt: Summarize this week's conversations and key insights
```

### Weather Alerts

```bash theme={null}
nullclaw cron add
# ID: weather_check
# Schedule: 0 7 * * *
# Prompt: Check weather and send Telegram message if rain expected
```

### Scheduled Notifications

```bash theme={null}
nullclaw cron add
# ID: standup_reminder
# Schedule: 55 8 * * 1-5
# Prompt: Send Slack message: Daily standup in 5 minutes!
```

## Running Scheduled Tasks

Tasks run automatically when:

1. **Gateway is running**: `nullclaw gateway`
2. **Service is installed**: `nullclaw service start`

The cron scheduler runs in the gateway process and executes tasks at their scheduled times.

## Execution Context

Scheduled tasks run with:

* Full agent context
* Access to all tools (subject to security policies)
* Memory persistence
* Channel access (can send messages to Telegram, Discord, etc.)

## Examples

### List all tasks

```bash theme={null}
nullclaw cron list
```

### Add a daily backup

```bash theme={null}
nullclaw cron add
# ID: daily_backup
# Schedule: 0 3 * * *
# Prompt: Create a memory snapshot and git commit
```

### Test a task

```bash theme={null}
# Run immediately
nullclaw cron run daily_backup

# Check execution
nullclaw cron list
# Should show updated "Last run" timestamp
```

### Remove old tasks

```bash theme={null}
nullclaw cron remove old_task_id
```

## Troubleshooting

### Task not running

1. Check gateway is running:
   ```bash theme={null}
   nullclaw service status
   ```

2. Verify cron expression:
   ```bash theme={null}
   # Test at https://crontab.guru/
   ```

3. Check task is enabled:
   ```bash theme={null}
   nullclaw cron list
   ```

### Invalid cron expression

```bash theme={null}
# Valid:
0 2 * * *        # Daily at 2 AM
*/15 * * * *     # Every 15 minutes

# Invalid:
* * * *          # Missing day-of-week field
60 2 * * *       # Minute > 59
```

## See Also

* [Gateway](/cli/gateway) - Run scheduled tasks
* [Service](/cli/service) - Background service
* [Agent](/cli/agent) - Test task prompts