Scheduled Task

Create, manage, and execute scheduled tasks using Claude CLI.

Quick Start

User Request → Parse Schedule → Generate Task MD → Register → Scheduler Executes → Notify

Create a Task

Parse the schedule type and generate task file:

python scripts/create_task.py \
  --name "Daily Code Review" \
  --schedule "cron:0 9 * * *" \
  --working-dir "/path/to/project" \
  --prompt "Review code quality in src/ directory"

Schedule Types

Type	Format	Example	Description
Cron	cron:expr	cron:0 9 * * *	Daily at 9am
Interval	interval:Xu	interval:30m	Every 30 minutes
Once	once:datetime	once:2026-01-27 15:00	One-time execution

Common Patterns

Pattern	Schedule
Every day at 9am	cron:0 9 * * *
Every hour	interval:1h
Every 30 minutes	interval:30m
Weekdays at 8am	cron:0 8 * * 1-5

Manage Tasks

# List all tasks
python scripts/list_tasks.py

# Cancel a task
python scripts/cancel_task.py --id task-001

# Run a task manually
python scripts/run_task.py --id task-001

# Start the scheduler (background)
python scripts/scheduler.py --daemon

Directory Structure (Runtime)

.scheduled-tasks/
├── registry.json          # Task registry
├── tasks/                 # Task MD files
│   └── task-001.md
├── results/               # Execution results
│   └── task-001_2026-01-26_09-00.md
└── logs/
    └── scheduler.log

Script Reference

create_task.py

Parameter	Required	Description
--name	Yes	Task name
--schedule	Yes	Schedule spec (cron:expr, interval:30m, once:datetime)
--prompt	Yes	Task instructions
--working-dir	No	Working directory (default: current)
--focus-files	No	File patterns to focus on

scheduler.py

Parameter	Description
--daemon	Run as background process
--once	Check and run due tasks once, then exit
--interval	Check interval in seconds (default: 60)

Cross-Platform Support

• Windows: Native toast notifications via win10toast
• macOS: osascript notifications
• Linux: notify-send (libnotify)

Dependencies

pip install -r scripts/requirements.txt

Error Handling

Error	Action
Claude CLI not found	Notify user, log error
Task timeout (5min default)	Kill process, mark failed, retry later
Invalid cron expression	Reject at creation time

Reference Files

• schedule-patterns.md - Complete schedule pattern reference