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

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:

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:

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

$ 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:

nullclaw cron remove morning_brief

cron pause / resume

Pause a task without removing it:

# Pause
nullclaw cron pause morning_brief

# Resume
nullclaw cron resume morning_brief

cron run

Run a task immediately (outside its schedule):

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:

{
  "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

nullclaw cron add
# ID: backup_memories
# Schedule: 0 2 * * *
# Prompt: Export all memories to ~/.nullclaw/backups/

Periodic Summaries

nullclaw cron add
# ID: weekly_summary
# Schedule: 0 18 * * 5
# Prompt: Summarize this week's conversations and key insights

Weather Alerts

nullclaw cron add
# ID: weather_check
# Schedule: 0 7 * * *
# Prompt: Check weather and send Telegram message if rain expected

Scheduled Notifications

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

nullclaw cron list

Add a daily backup

nullclaw cron add
# ID: daily_backup
# Schedule: 0 3 * * *
# Prompt: Create a memory snapshot and git commit

Test a task

# Run immediately
nullclaw cron run daily_backup

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

Remove old tasks

nullclaw cron remove old_task_id

Troubleshooting

Task not running

1. Check gateway is running:

   nullclaw service status
   

2. Verify cron expression:

   # Test at https://crontab.guru/
   

3. Check task is enabled:

   nullclaw cron list
   

Invalid cron expression

# Valid:
0 2 * * *        # Daily at 2 AM
*/15 * * * *     # Every 15 minutes

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

See Also

• Gateway - Run scheduled tasks
• Service - Background service
• Agent - Test task prompts