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