Schedule Skill

Manage cron-based scheduled tasks that deliver messages to the tinyclaw queue via the API server. Each schedule fires at a cron interval and POSTs a routed message (@agent_id <task> ) to POST /api/message , where the queue processor picks it up and invokes the target agent.

Commands

Use the bundled CLI scripts/schedule.sh for all operations.

Create a schedule

scripts/schedule.sh create
--cron "EXPR"
--agent AGENT_ID
--message "Task context for the agent"
[--channel CHANNEL]
[--sender SENDER]
[--label LABEL]

• --cron — 5-field cron expression (required). Examples: "0 9 * * " (daily 9am), "/30 * * * *" (every 30 min), "0 0 * * 1" (weekly Monday midnight).

• --agent — Target agent ID (required). Must match an agent configured in settings.json.

• --message — The task context / prompt sent to the agent (required).

• --channel — Channel name in the queue message (default: schedule ).

• --sender — Sender name in the queue message (default: Scheduler ).

• --label — Unique label to identify this schedule (default: auto-generated). Use a descriptive label for easy management.

List schedules

scripts/schedule.sh list [--agent AGENT_ID]

Lists all tinyclaw schedules. Optionally filter by --agent to show only schedules targeting a specific agent.

Delete a schedule

scripts/schedule.sh delete --label LABEL scripts/schedule.sh delete --all

Delete a specific schedule by label, or delete all tinyclaw schedules.

Workflow

• Confirm the target agent ID exists (check settings.json or ask the user).

• Determine the cron expression from the user's description (e.g., "every morning" → "0 9 * * *" ).

• Compose a clear task message — this is the prompt the agent will receive.

• Run scripts/schedule.sh create with the parameters.

• Verify with scripts/schedule.sh list .

Cron expression quick reference

┌───────────── minute (0-59) │ ┌───────────── hour (0-23) │ │ ┌───────────── day of month (1-31) │ │ │ ┌───────────── month (1-12) │ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday) │ │ │ │ │

Pattern Meaning

0 9 * * *

Daily at 9:00 AM

0 9 * * 1-5

Weekdays at 9:00 AM

*/15 * * * *

Every 15 minutes

0 */2 * * *

Every 2 hours

0 0 * * 0

Weekly on Sunday midnight

0 0 1 * *

Monthly on the 1st

30 8 * * 1

Monday at 8:30 AM

Examples

Daily report

scripts/schedule.sh create
--cron "0 9 * * *"
--agent analyst
--message "Generate the daily metrics report and post a summary"
--label daily-report

Periodic health check

scripts/schedule.sh create
--cron "*/30 * * * *"
--agent devops
--message "Run health checks on all services and report any issues"
--label health-check

Weekly code review reminder

scripts/schedule.sh create
--cron "0 10 * * 1"
--agent coder
--message "Review open PRs and summarize status"
--label weekly-pr-review

List and clean up

See all schedules

scripts/schedule.sh list

See only schedules for @coder

scripts/schedule.sh list --agent coder

Remove one

scripts/schedule.sh delete --label health-check

Remove all

scripts/schedule.sh delete --all

How it works

• Schedules are stored as system cron entries tagged with # tinyclaw-schedule:<label> .

• When a cron job fires, it POSTs a message to the API server (POST /api/message ) with the @agent_id routing prefix.

• The queue processor picks up the message and invokes the target agent, exactly like a message from any channel.

• Responses are stored in the SQLite queue and delivered by channel clients.

For queue message format details, see references/queue-format.md .