Skip to main content
The schedule_task tool creates a new scheduled task that runs as a full agent with access to all tools and the group’s context.

​
Overview

Scheduled tasks in NanoClaw are powerful - they run as complete agents with:
  • Full access to all tools (WebSearch, file operations, etc.)
  • The group’s conversation context (if using context_mode: "group")
  • Ability to send messages to the user
  • Their own working directory and memory

​
Signature

schedule_task(
  prompt: string,
  schedule_type: 'cron' | 'interval' | 'once',
  schedule_value: string,
  context_mode?: 'group' | 'isolated',
  target_group_jid?: string
): { taskId: string }

​
Parameters

​
prompt
string
required
Instructions for what the agent should do when the task runs. For isolated mode, include all necessary context in the prompt since the agent won’t have access to conversation history.
​
schedule_type
enum
required
The type of schedule to use.
  • cron - Recurring at specific times using cron expressions
  • interval - Recurring every N milliseconds
  • once - Run once at a specific time
​
schedule_value
string
required
The schedule value in a format matching the schedule_type:
  • For cron: Standard cron expression (e.g., "*/5 * * * *" for every 5 minutes)
  • For interval: Milliseconds as a string (e.g., "300000" for 5 minutes)
  • For once: Local timestamp WITHOUT “Z” suffix (e.g., "2026-02-01T15:30:00")
Important: All times are in local timezone, not UTC.
​
context_mode
enum
default:"group"
Controls whether the task agent has access to conversation history.
  • group - Task runs with chat history and memory (use for tasks that need conversation context)
  • isolated - Task runs in a fresh session with no history (use for independent tasks)
When to use each mode:
  • “Remind me about our discussion” → group (needs conversation context)
  • “Check the weather every morning” → isolated (self-contained task)
  • “Follow up on my request” → group (needs to know what was requested)
  • “Generate a daily report” → isolated (just needs instructions in prompt)
​
target_group_jid
string
(Main group only) JID of the group to schedule the task for. Defaults to the current group.This parameter is ignored for non-main groups - they can only schedule tasks for themselves.

​
Return Value

​
taskId
string
The unique identifier for the scheduled task. Use this ID with other task management tools like update_task, pause_task, or cancel_task.Format: task-{timestamp}-{random}Example: task-1706745600000-a1b2c3

​
Schedule Types

​
Cron Expressions

Cron expressions follow 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 to Saturday)
│ │ │ │ │
* * * * *
Examples: 
schedule_task({
  prompt: "Check for updates",
  schedule_type: "cron",
  schedule_value: "*/5 * * * *"
});

​
Interval (Milliseconds)

For simple recurring tasks, use milliseconds: 
schedule_task({
  prompt: "Check server status",
  schedule_type: "interval",
  schedule_value: "300000" // 5 * 60 * 1000
});

​
One-Time Tasks

Schedule a task to run once at a specific time: 
schedule_task({
  prompt: "Remind me about the meeting",
  schedule_type: "once",
  schedule_value: "2026-02-01T15:30:00" // Local time, no Z suffix!
});
Important: For once schedules, do NOT use UTC/Z suffix. The timestamp must be in local time format.

​
Messaging Behavior

The task agent’s output is automatically sent to the user or group. The agent can also:
  • Use send_message tool for immediate message delivery during execution
  • Wrap output in <internal> tags to suppress automatic sending
Include guidance in your prompt about when to send messages:
  • Always send (reminders, daily briefings)
  • Only when there’s something to report (“notify me if…”)
  • Never send (background maintenance tasks)

​
Examples

schedule_task({
  prompt: "Review our conversation from yesterday and remind me about any action items I committed to. Be specific about what I said I would do.",
  schedule_type: "cron",
  schedule_value: "0 9 * * *", // 9am daily
  context_mode: "group" // Needs conversation history
});

​
Validation

The tool validates the schedule_value before creating the task:
  • Cron: Parses the expression using cron-parser and returns an error if invalid
  • Interval: Checks that the value is a positive integer
  • Once: Validates timestamp format and rejects UTC/timezone suffixes

​
IPC Implementation

When called, the tool writes a JSON file to /workspace/ipc/tasks/: 
{
  type: 'schedule_task',
  taskId: 'task-1706745600000-a1b2c3',
  prompt: 'Check for updates',
  schedule_type: 'cron',
  schedule_value: '*/5 * * * *',
  context_mode: 'group',
  targetJid: '[email protected]',
  createdBy: 'whatsapp_main',
  timestamp: '2026-02-01T12:00:00.000Z'
}
The host process monitors this directory and processes new task files.

Build docs developers (and LLMs) love

Get started for freeTalk to us