Scheduled Tasks

📖 Best for: All roles — people who want AI to auto-run tasks on schedule (monitoring, reports, backups, content generation) without manual operation every day

📖 Reading time: 3 minutes

📖 In one sentence: YingClaw’s built-in scheduler that lets your AI assistant auto-execute tasks on schedule, supporting 3 schedule modes (cron / at / every) and 2 task types (shell / agent), with multi-task concurrency, per-task timeout, and auto-disable after N consecutive failures. Triggered by natural language ("check disk at 9 every day") or explicit cron_add / cron_list / cron_runs tool calls. All roles, each user has an independent task list.

---

I. Core Value

Value	Description
Automation	7×24 unattended — monitoring, reports, backups, content generation all run automatically
Two task types	shell (run commands) + agent (delegate to AI) — covers all automation scenarios
Multi-task concurrency	Multiple tasks run in parallel, no blocking; high-priority tasks can preempt
Resilient & safe	Per-task timeout, failure retry, auto-disable after N consecutive failures — prevents runaways

II. Main Capabilities

1. Three Schedule Modes

Mode	Description	Example
cron	Standard cron expression (5 fields: min hour day month weekday)	0 9 * * * (daily 9 am), */5 * * * * (every 5 min)
at	Execute once at a specified time	2026-12-31T23:59:00Z (Spring Festival midnight)
every	Recurring at fixed interval	every 30m (every 30 min)

Cron shortcuts: @hourly / @daily / @weekly / @monthly / @yearly.

2. Shell Task

Runs a shell command / script on schedule; auto-captures stdout / stderr / exit code; output > 1MB truncated and written to log.

cron_add(
  job_type="shell",
  command="df -h | grep '/dev'",
  schedule={"kind": "cron", "expr": "0 9 * * *"},  # daily at 9 am
  name="check-disk-daily",
  timeout_secs=300
)

3. Agent Task

Delegates to AI agent to execute natural-language instructions; supports delivery to IM; session_target="isolated" runs in independent session without polluting main chat.

cron_add(
  job_type="agent",
  prompt="check server disk, if any partition > 80% immediately send alert",
  schedule={"kind": "cron", "expr": "0 9 * * *"},
  delivery={"mode": "announce", "channel": "telegram", "to": "ops_chat_id"},
  session_target="isolated"
)

4. Multi-Task Concurrency

• Multiple tasks run in parallel, no blocking
• Default concurrency = 4, dynamically scheduled by CPU / memory
• Critical tasks set priority="high" to preempt
• Task dependencies: A finishes before B runs, use depends_on=["task-a-id"]

5. Timeout Control

• timeout_secs sets max execution time per task
• shell task timeout → kill process; agent task timeout → interrupt agent, return partial result
• Default timeout: shell 5 min, agent 10 min

6. Auto-Disable (Failure Protection)

• end_after_runs auto-stops after N runs (e.g., emergency deploy window)
• Auto-disable after N consecutive failures (default 3) — prevents log spam
• Failure reason + auto-disable time recorded in cron_runs history

7. Task Management API

Tool	Role
cron_add	Create a task
cron_list	List all tasks
cron_update	Modify task (pause / resume / change cron)
cron_remove	Delete a task
cron_runs	View execution history
cron_run	Manually trigger once (for testing)

Pure shell tasks can also use the schedule tool, lighter weight.

8. Execution History & Logs

• cron_runs(job_id, limit=10) shows the latest N runs
• Each record has: start / end time, status (success / failed / timeout), output summary, error info
• Failed tasks can be rerun with one click (cron_run)

III. Typical Use Cases

Use Case 1: Server Health Check — "Check disk every morning at 9"

shell task: cron 0 9 * * *  →  run df -h, alert if usage > 80%

Ops health checks (disk / memory / service / log) all run automatically, anomalies pushed immediately.

Use Case 2: Scheduled Reports — "Generate last-week sales report every Monday"

agent task: cron 0 9 * * 1  →  pull data → generate Excel → push to WeChat group

Business reports (weekly / monthly / daily) auto-generated + auto-pushed, no more manual work.

Use Case 3: Website Monitoring — "Check if website is up every 5 minutes"

shell task: cron */5 * * * *  →  curl check HTTP 200, notify on failure

Uptime monitoring (HTTP status / response time / SSL cert) runs continuously, alerts instantly on outage.

Use Case 4: Data Backup — "Backup database every day at 3 am"

shell task: cron 0 3 * * *  →  mysqldump → gzip → write to /backup/

Data backups (DB / files / config) run on schedule, old backups auto-cleaned.

Use Case 5: AI Content Auto-Generation — "Generate AI news digest every day at 8 am"

agent task: cron 0 8 * * *  →  web_search → distill 5 items → push to Telegram

Content automation (news digest / competitor monitoring / sentiment analysis) handled end-to-end with agent tasks.

IV. Usage Guide

Step 1: Create with natural language — say "check disk every day at 9", "generate sales report every Monday", "monitor website every 5 minutes"; YingClaw auto-translates to cron expression + task.

Step 2: Explicit cron_add call — for complex tasks use cron_add(name, schedule, command/prompt, job_type, ...): pick job_type shell / agent; schedule cron / at / every; timeout_secs required; critical tasks add delivery to push to IM.

Step 3: Manage tasks — cron_list to view all; cron_runs <id> to view history; cron_update <id> {"enabled": false} to pause; cron_remove <id> to delete.

Step 4: Handle failures — check cron_runs error info → fix command / prompt → cron_update → manually cron_run once to test → resume schedule.

Step 5: Clean up tasks — transient tasks (Spring Festival greetings, one-off events) use at, runs once and ends automatically; long-term tasks add end_after_runs to avoid indefinite execution.

V. Best Practices

• Timezone must be explicit — cron defaults to server timezone; Chinese users explicitly use +08:00 or set TZ=Asia/Shanghai to avoid early-morning task drift
• Tasks must be idempotent — running twice yields the same result as once (INSERT ... ON DUPLICATE KEY UPDATE, overwrite writes), avoids repeated execution polluting data
• Add timeout protection — set timeout_secs for every task, prevents a stuck task from occupying concurrency slots
• Failures must be observable — critical tasks add delivery to push to IM, know failures immediately
• Names must be clear — daily-disk-check is 10× better than task1; team collaboration locates issues instantly
• Don't set too frequent — every-minute / every-30s tasks use with caution, can overwhelm monitored services; monitoring class start at 5 minutes
• Prefer every for simple loops — every N minutes / hours / days use every, more intuitive than cron expression
• Complex tasks use agent — natural language + multi-step ops (query data + generate report + push) use agent task, more stable than shell command chains
• Critical tasks use isolated session — session_target="isolated" runs in independent session, doesn't pollute main chat context
• Audit cron_list regularly — monthly sweep: delete expired, fix misplaced, merge duplicates, keep scheduler clean