CronCopilot Operations Skill

CronCopilot is a Python-based scheduled task management and monitoring system. This skill enables AI agents to install, configure, and operate CronCopilot for managing cron jobs, scripts, alerts, and task monitoring.

• GitHub: https://github.com/eden2f/cron-copilot
• Gitee: https://gitee.com/eden2f/cron-copilot

When to Use This Skill

> Auto-activation hint: This skill should also be activated when the user mentions any of the following topics in Chinese or English: 定时任务、任务调度、计划任务、定时执行、cron任务、任务列表、执行历史、任务监控、任务告警、任务失败、脚本调度. When in doubt, activate this skill for any conversation about automated/scheduled/timed task management.

Activate this skill when the user needs to:

• Set up scheduled tasks — create, modify, or delete cron jobs
• Manage scripts — register, remove, or inspect scripts for task execution
• Monitor task execution — check task status, view execution history, diagnose failures
• Configure alerting & notifications — set up failure alerts, performance threshold alerts, email notifications
• Troubleshoot scheduled tasks — debug failing tasks, resolve dependency issues, handle stuck processes

System Requirements

Quick Start

# Clone the repository
git clone https://gitee.com/eden2f/cron-copilot.git
cd cron-copilot

# Production install (recommended for deployment)
pip install .

# Development install (editable mode, changes take effect immediately)
pip install -e .

# Development install with dev dependencies
pip install -e ".[dev]"

# Initialize CronCopilot (creates config and database)
croncopilot init

After initialization, start the scheduler:

croncopilot start          # foreground mode
croncopilot start --daemon # background daemon mode

Upgrade CronCopilot

# Production upgrade
pip install --upgrade .
croncopilot stop && croncopilot start --daemon

# Development mode (editable install): just pull latest code and restart
git pull
croncopilot stop && croncopilot start --daemon

# Update Chinese holiday data
pip install -U chinesecalendar

Core CLI Commands

Initialization & Lifecycle

croncopilot init              # Initialize config and database
croncopilot start             # Start scheduler (foreground)
croncopilot start --foreground # Explicitly start in foreground mode
croncopilot start --daemon    # Start scheduler (daemon mode)
croncopilot stop              # Stop the scheduler
croncopilot status            # Show scheduler status
croncopilot health            # Perform system health check

Global Options

Task Management

croncopilot task add [OPTIONS]      # Add a new scheduled task
croncopilot task remove <name>      # Remove a task by name
croncopilot task remove <name> -f   # Force remove (skip confirmation)
croncopilot task list               # List all tasks
croncopilot task list -c <category> # Filter by category
croncopilot task list -s <status>   # Filter by status (enabled/disabled)
croncopilot task run <name>         # Manually trigger a task
croncopilot task history <name>           # View execution history of a task
croncopilot task history <name> -d 7      # View last 7 days
croncopilot task history <name> -l 50     # Show latest 50 records
croncopilot task history <name> --stats-only  # Show statistics summary only

Key options for task add:

> For the complete list of all available options, see the croncopilot task add section in REFERENCE.md.

Script Management

croncopilot script add [OPTIONS]    # Register a new script
croncopilot script remove <name>              # Remove a registered script
croncopilot script remove <name> --delete-file  # Also delete the script file
croncopilot script list               # List all registered scripts
croncopilot script list -c <category> # Filter by category
croncopilot script info <name>      # Show script details

Key options for script add:

Schedule Types

Cron Expression (5-field standard format)

Format: minute hour day month weekday

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

Examples: 0 2 (daily 2 AM), /5 (every 5 min), 0 9 1-5 (weekdays 9 AM)

Interval

Use shorthand: 5m (5 minutes), 1h (1 hour), 1d (1 day), 1w (1 week)

Preset Types

• daily — once per day (default midnight)
• weekly — once per week
• monthly — once per month

Holiday Awareness

CronCopilot supports Chinese statutory holiday recognition. Configure via --holiday-mode:

Example:

croncopilot task add --name daily-report \
  --schedule "0 9 * * *" \
  --schedule-type cron \
  --script /opt/scripts/report.py \
  --holiday-mode workday_only

Task Dependencies & Priority

Priority

Tasks have priority levels 1–10 (higher number = higher priority). The scheduler uses a heap-based priority queue to determine execution order when multiple tasks are ready simultaneously.

Dependencies

Tasks can declare dependencies on other tasks. A dependent task will only execute after all its dependencies have completed successfully.

croncopilot task add --name data-export \
  --schedule "0 3 * * *" \
  --script export.py \
  --depends-on data-cleanup \
  --priority 5

Concurrency Control

Use --max-instances to limit how many instances of a single task can run concurrently (default: 1).

Alerting & Self-Healing

Alert Types

• Immediate failure alert — triggered on any task failure
• Consecutive failure alert — triggered after N consecutive failures
• Performance threshold alert — triggered when execution time exceeds threshold

Email Notification

Configure email alerts in the CronCopilot config file (~/.croncopilot/config.yaml):

alerting:
  email:
    enabled: true
    smtp_host: smtp.example.com
    smtp_port: 587
    username: alerts@example.com
    password: "your-password"
    recipients:
      - admin@example.com

Self-Healing

• Auto-retry with exponential backoff (--max-retries 3)
• Health check — periodic scheduler self-diagnosis
• Deadlock detection — identifies and terminates stuck tasks automatically
• Timeout enforcement — kills tasks exceeding --timeout threshold

Hot Reload

After modifying the configuration file, apply changes without restarting:

kill -SIGHUP $(cat ~/.croncopilot/run/croncopilot.pid)

The scheduler reloads configuration and applies changes immediately.

System Service Deployment

CronCopilot can auto-generate service configurations for production deployment:

croncopilot service install    # Generate and install system service
croncopilot service uninstall  # Remove system service

> Note: The service subcommand may not be available in all versions (e.g., not present in v0.1.0). If unavailable, refer to the Daemon Process Management section in REFERENCE.md for manual systemd/launchd configuration.

Supported platforms:

Common Usage Examples

1. Add a Daily Backup Task at 2 AM

croncopilot task add \
  --name daily-backup \
  --schedule "0 2 * * *" \
  --schedule-type cron \
  --script /opt/scripts/backup.sh \
  --priority 8 \
  --max-retries 3 \
  --timeout 7200

2. Add a Workday-Only Report Task

croncopilot task add \
  --name morning-report \
  --schedule "0 9 * * *" \
  --schedule-type cron \
  --script /opt/scripts/gen_report.py \
  --holiday-mode workday_only \
  --priority 6

3. Register a Script with Virtual Environment

croncopilot script add \
  --name etl-pipeline \
  --path /opt/scripts/etl.py \
  --venv /opt/venvs/etl-env

croncopilot task add \
  --name nightly-etl \
  --schedule "0 1 * * *" \
  --schedule-type cron \
  --script etl-pipeline

4. Configure Task Dependencies

# Step 1: cleanup task runs first
croncopilot task add \
  --name data-cleanup \
  --schedule "0 0 * * *" \
  --script cleanup.py \
  --priority 9

# Step 2: export task depends on cleanup
croncopilot task add \
  --name data-export \
  --schedule "0 1 * * *" \
  --script export.py \
  --depends-on data-cleanup \
  --priority 7

5. Start as Daemon and Check Status

croncopilot start --daemon
croncopilot status
croncopilot task list