Back to Details

scheduler

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scheduling Assistant

调度助手

You help users set up and manage scheduled Claude Code tasks. You can:
  • Convert natural language to cron expressions ("every weekday at 9am" -> "0 9 * * 1-5")
  • Explain cron syntax and scheduling concepts
  • Set up native OS schedulers (launchd, cron, Task Scheduler)
  • Troubleshoot scheduling issues
  • Suggest automation patterns for common workflows
您可以借助我来设置和管理Claude Code的定时任务。我能：
  • 将自然语言转换为cron表达式（例如“每个工作日上午9点” → "0 9 * * 1-5"）
  • 解释cron语法和调度相关概念
  • 配置操作系统原生调度器（launchd、cron、任务计划程序）
  • 排查调度相关问题
  • 针对常见工作流提供自动化模式建议

Quick Start

快速开始

To create a scheduled task:
/scheduler:schedule-add
To view all scheduled tasks:
/scheduler:schedule-list
创建定时任务：
/scheduler:schedule-add
查看所有定时任务：
/scheduler:schedule-list

One-Time vs Recurring Tasks

一次性任务 vs 周期性任务

The scheduler supports both one-time and recurring tasks:
调度器同时支持一次性和周期性任务：

One-Time Tasks

一次性任务

For tasks that run once at a specific time:
  • "run at 3pm today"
  • "tomorrow at noon"
  • "next Tuesday at 2pm"
One-time tasks automatically clean up after execution.
适用于仅在特定时间运行一次的任务：
  • “今天下午3点运行”
  • “明天中午运行”
  • “下周二下午2点运行”
一次性任务执行后会自动清理。

Recurring Tasks

周期性任务

For tasks that repeat on a schedule:
  • "every day at 9am"
  • "daily at 6pm"
  • "weekdays at 10am"
  • Cron expressions like 
    0 9 * * 1-5
Detection rule: Unless "every", "daily", "weekly", or similar recurring keywords are present, the task is treated as one-time.
适用于按固定周期重复运行的任务：
  • “每天上午9点运行”
  • “每天下午6点运行”
  • “工作日上午10点运行”
  • 类似 
    0 9 * * 1-5
    的cron表达式
识别规则： 除非请求中包含“every”“daily”“weekly”等表示周期性的关键词，否则任务将被视为一次性任务。

Git Worktree Mode (Isolated Branches)

Git Worktree 模式（隔离分支）

For tasks that make changes, worktree mode runs them in isolation:
You: Every night at 2am, refactor deprecated API calls and push for review

Claude: Should this run in an isolated git worktree?
        → Yes, create branch and push changes
        → No, run in main working directory

You: Yes

Claude: ✓ Task created with worktree isolation
        Branch prefix: claude-task/
        Remote: origin
How it works:
  1. Task triggers → creates fresh worktree with new branch
  2. Claude runs in the worktree (isolated from main)
  3. Changes are committed and pushed to remote
  4. Worktree is cleaned up after successful push
  5. You review the PR at your convenience
Configuration options:
OptionDefaultDescription
worktree.enabled
false
Enable worktree isolation
worktree.branchPrefix
"claude-task/"
Branch name prefix
worktree.remoteName
"origin"
Remote to push to
If push fails, the worktree is kept for manual review.
对于会产生变更的任务，工作树模式可将其在隔离环境中运行：
您：每天凌晨2点，重构已废弃的API调用并推送至远程仓库等待审查

Claude：是否要在隔离的git worktree中运行此任务？
        → 是，创建分支并推送变更
        → 否，在主工作目录中运行

您：是

Claude：✓ 已创建带worktree隔离的任务
        分支前缀：claude-task/
        远程仓库：origin
工作原理：
  1. 任务触发 → 创建新分支的独立worktree
  2. Claude在该worktree中执行任务（与主目录隔离）
  3. 变更被提交并推送至远程仓库
  4. 推送成功后自动清理worktree
  5. 您可在方便时审查PR
配置选项：
选项默认值描述
worktree.enabled
false
启用worktree隔离
worktree.branchPrefix
"claude-task/"
分支名称前缀
worktree.remoteName
"origin"
推送目标远程仓库
若推送失败，worktree会被保留以便手动审查。

Cron Quick Reference

Cron 速查指南

* * * * *
| | | | |
| | | | +-- Day of week (0-6, Sun=0)
| | | +---- Month (1-12)
| | +------ Day of month (1-31)
| +-------- Hour (0-23)
+---------- Minute (0-59)
Common patterns:
PatternDescription
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 9 1 * *
First of month at 9:00 AM
0 9 * * 1
Every Monday at 9:00 AM
For complete syntax, see CRON_REFERENCE.md.
* * * * *
| | | | |
| | | | +-- 星期几 (0-6，周日=0)
| | | +---- 月份 (1-12)
| | +------ 日期 (1-31)
| +-------- 小时 (0-23)
+---------- 分钟 (0-59)
常见模式：
模式描述
0 9 * * *
每天上午9:00
0 9 * * 1-5
工作日上午9:00
*/15 * * * *
每15分钟一次
0 */2 * * *
每2小时一次
0 9 1 * *
每月1日上午9:00
0 9 * * 1
每周一上午9:00
完整语法请参考 CRON_REFERENCE.md。

Platform Setup

平台配置

Tasks are executed by your OS's native scheduler:
  • macOS: launchd (LaunchAgents)
  • Linux: crontab
  • Windows: Task Scheduler
For platform-specific details, see PLATFORM_SETUP.md.
任务由操作系统的原生调度器执行：
  • macOS： launchd（LaunchAgents）
  • Linux： crontab
  • Windows： 任务计划程序
平台相关详细说明请参考 PLATFORM_SETUP.md。

Common Use Cases

常见使用场景

Daily Code Review

每日代码审查

Schedule: 0 9 * * 1-5 (weekdays at 9am)
Command: /review-code --scope=yesterday
调度规则：0 9 * * 1-5（工作日上午9点）
命令：/review-code --scope=yesterday

Weekly Dependency Audit

每周依赖审计

Schedule: 0 10 * * 1 (Mondays at 10am)
Command: Check for outdated dependencies and security vulnerabilities
调度规则：0 10 * * 1（每周一上午10点）
命令：检查过期依赖项和安全漏洞

Automated Testing

自动化测试

Schedule: 0 */4 * * * (every 4 hours)
Command: Run test suite and report failures
调度规则：0 */4 * * *（每4小时一次）
命令：运行测试套件并报告失败情况

Troubleshooting

故障排查

Task not running?
  1. Check 
    /scheduler:schedule-status
    for health
  2. Verify task is enabled: 
    /scheduler:schedule-list
  3. Check logs: 
    /scheduler:schedule-logs <task-id>
  4. Ensure 
    claude
    CLI is in PATH for scheduler
Common issues:
  • PATH not set correctly in scheduler environment
  • Working directory doesn't exist
  • Command syntax errors
  • Scheduler daemon not running
任务未运行？
  1. 执行 
    /scheduler:schedule-status
    检查健康状态
  2. 验证任务是否启用：
    /scheduler:schedule-list
  3. 查看日志：
    /scheduler:schedule-logs <task-id>
  4. 确保调度器环境的PATH中包含
    claude
    CLI
常见问题：
  • 调度器环境中的PATH配置不正确
  • 工作目录不存在
  • 命令语法错误
  • 调度器守护进程未运行

Helper Scripts

辅助脚本

To validate a cron expression:
bash
python scripts/parse-cron.py "0 9 * * 1-5"
验证cron表达式：
bash
python scripts/parse-cron.py "0 9 * * 1-5"

Available Commands

可用命令

CommandDescription
/scheduler:schedule-add
Create a new scheduled task
/scheduler:schedule-list
View all scheduled tasks
/scheduler:schedule-remove <id>
Remove a scheduled task
/scheduler:schedule-status
Check scheduler health
/scheduler:schedule-run <id>
Manually run a task
/scheduler:schedule-logs <id>
View execution logs
命令描述
/scheduler:schedule-add
创建新的定时任务
/scheduler:schedule-list
查看所有定时任务
/scheduler:schedule-remove <id>
删除指定定时任务
/scheduler:schedule-status
检查调度器健康状态
/scheduler:schedule-run <id>
手动运行指定任务
/scheduler:schedule-logs <id>
查看任务执行日志