Task Management Tools - NanoClaw Pro

NanoClaw provides a suite of tools for managing scheduled tasks throughout their lifecycle.

list_tasks

List all scheduled tasks. From the main group, this shows all tasks across all groups. From other groups, it only shows that group’s tasks.

Signature

list_tasks(): { content: [{ type: 'text', text: string }] }

Parameters

No parameters required.

Return Value

content

array

Array with a single text content item containing formatted task list.Format:

Scheduled tasks:
- [task-id] Prompt preview... (cron: 0 9 * * *) - active, next: 2026-02-01T09:00:00Z
- [task-id] Another task... (interval: 3600000) - paused, next: N/A

Example

const result = await mcp__nanoclaw__list_tasks({});
// Shows only this group's tasks

Implementation

The tool reads from /workspace/ipc/current_tasks.json, which is maintained by the host process:

const tasksFile = path.join(IPC_DIR, 'current_tasks.json');
const allTasks = JSON.parse(fs.readFileSync(tasksFile, 'utf-8'));

const tasks = isMain
  ? allTasks
  : allTasks.filter((t) => t.groupFolder === groupFolder);

update_task

Modify an existing scheduled task. Only provided fields are changed; omitted fields remain unchanged.

Signature

update_task(
  task_id: string,
  prompt?: string,
  schedule_type?: 'cron' | 'interval' | 'once',
  schedule_value?: string
): { content: [{ type: 'text', text: string }] }

Parameters

task_id

string

required

The ID of the task to update. Obtain this from list_tasks or from the return value of schedule_task.

prompt

string

New instructions for what the agent should do when the task runs. If omitted, the existing prompt is unchanged.

schedule_type

enum

New schedule type: cron, interval, or once. If omitted, the existing type is unchanged.

schedule_value

string

New schedule value (format depends on schedule_type). If omitted, the existing value is unchanged.See schedule_task for format details.

Return Value

content

array

Confirmation message indicating the update was requested.

Validation

The tool validates the new schedule value if provided:

Cron expressions are parsed with cron-parser
Interval values must be positive integers
Timestamps must be valid dates

Examples

update_task({
  task_id: "task-1706745600000-a1b2c3",
  prompt: "Updated instructions: check for emails and summarize urgent ones only"
});

pause_task

Pause a scheduled task. The task will not run until it is resumed with resume_task.

Signature

pause_task(task_id: string): { content: [{ type: 'text', text: string }] }

Parameters

task_id

string

required

The ID of the task to pause.

Return Value

content

array

Confirmation message: "Task {task_id} pause requested."

Example

pause_task({ task_id: "task-1706745600000-a1b2c3" });

resume_task

Resume a paused task. The task will continue running on its schedule.

Signature

resume_task(task_id: string): { content: [{ type: 'text', text: string }] }

Parameters

task_id

string

required

The ID of the task to resume.

Return Value

content

array

Confirmation message: "Task {task_id} resume requested."

Example

resume_task({ task_id: "task-1706745600000-a1b2c3" });

cancel_task

Permanently delete a scheduled task. This action cannot be undone.

Signature

cancel_task(task_id: string): { content: [{ type: 'text', text: string }] }

Parameters

task_id

string

required

The ID of the task to cancel and delete.

Return Value

content

array

Confirmation message: "Task {task_id} cancellation requested."

Example

cancel_task({ task_id: "task-1706745600000-a1b2c3" });

send_message

Send a message to the user or group immediately while the agent is still running. This is useful for:

Progress updates during long-running tasks
Sending multiple messages in sequence
Immediate feedback before the agent completes

Signature

send_message(
  text: string,
  sender?: string
): { content: [{ type: 'text', text: string }] }

Parameters

text

string

required

The message text to send to the user or group.

sender

string

Optional role or identity name (e.g., “Researcher”, “Reporter”). When set, messages appear from a dedicated bot in Telegram (or similar for other channels that support it).This is useful for multi-agent scenarios where you want to distinguish between different agent roles.

Return Value

content

array

Confirmation message: "Message sent."

Examples

send_message({
  text: "I'm starting the analysis now. This might take a few minutes."
});

IPC Implementation

The tool writes a JSON file to /workspace/ipc/messages/:

{
  type: 'message',
  chatJid: '[email protected]',
  text: 'Progress update',
  sender: 'Researcher', // optional
  groupFolder: 'whatsapp_main',
  timestamp: '2026-02-01T12:00:00.000Z'
}

The host process monitors this directory and routes messages to the appropriate channel.

Permissions

All task management tools respect group boundaries:

Tool	Non-Main Groups	Main Group
`list_tasks`	Shows only this group’s tasks	Shows all tasks
`update_task`	Can update own tasks only	Can update any task
`pause_task`	Can pause own tasks only	Can pause any task
`resume_task`	Can resume own tasks only	Can resume any task
`cancel_task`	Can cancel own tasks only	Can cancel any task
`send_message`	Sends to own group only	Sends to own group only

Common Patterns

Conditional task management

// List tasks and pause active ones
const result = await list_tasks({});
const taskIds = parseTaskIds(result); // Extract IDs from formatted output

for (const taskId of taskIds) {
  await pause_task({ task_id: taskId });
}

Update task schedule based on time of day

const hour = new Date().getHours();
const newSchedule = hour < 18 ? "0 9 * * *" : "0 7 * * *";

await update_task({
  task_id: "task-1706745600000-a1b2c3",
  schedule_type: "cron",
  schedule_value: newSchedule
});

Send progress updates during long task

await send_message({ text: "Starting weekly report generation..." });

// Collect data
const data = await fetchData();
await send_message({ text: `Collected ${data.length} items. Analyzing...` });

// Analyze
const analysis = await analyzeData(data);
await send_message({ text: "Analysis complete. Generating report..." });

// Generate report
const report = await generateReport(analysis);
await send_message({ text: report });

MCP Tools

Channel Interface

​list_tasks

​Signature

​Parameters

​Return Value

​Example

​Implementation

​update_task

​Signature

​Parameters

​Return Value

​Validation

​Examples

​pause_task

​Signature

​Parameters

​Return Value

​Example

​resume_task

​Signature

​Parameters

​Return Value

​Example

​cancel_task

​Signature

​Parameters

​Return Value

​Example

​send_message

​Signature

​Parameters

​Return Value

​Examples

​IPC Implementation

​Permissions

​Common Patterns

​Conditional task management

​Update task schedule based on time of day

​Send progress updates during long task

Build docs developers (and LLMs) love

list_tasks

Signature

Parameters

Return Value

Example

Implementation

update_task

Signature

Parameters

Return Value

Validation

Examples

pause_task

Signature

Parameters

Return Value

Example

resume_task

Signature

Parameters

Return Value

Example

cancel_task

Signature

Parameters

Return Value

Example

send_message

Signature

Parameters

Return Value

Examples

IPC Implementation

Permissions

Common Patterns

Conditional task management

Update task schedule based on time of day

Send progress updates during long task