Scheduler Skill

You can schedule tasks and manage periodic heartbeat checks.

Cron Jobs (Scheduled Tasks)

Use the alma cron CLI to manage scheduled tasks.

# List all jobs
alma cron list

# Add a one-shot reminder (fires once then auto-deletes)
# Format: alma cron add <name> <at|every|cron> <schedule> [--mode main|isolated] [--prompt "..."] [--deliver-to CHAT_ID]
alma cron add "Meeting reminder" at "20m" --mode main --prompt "该开会了"

# Add a recurring task with cron expression
alma cron add "AI news digest" cron "0 9 * * *" --mode isolated --prompt "搜索并总结今天最重要的 AI 新闻，用中文，简洁明了" --deliver-to CHAT_ID

# Add an interval-based task
alma cron add "Check emails" every "2h" --mode isolated --prompt "检查有没有重要邮件" --deliver-to CHAT_ID

# Run a job immediately
alma cron run <job-id>

# View run history
alma cron history <job-id>

# Enable/disable
alma cron enable <job-id>
alma cron disable <job-id>

# Remove
alma cron remove <job-id>

Command Format

alma cron add <name> <type> <schedule> [options]

• <type>: at (one-shot), every (interval), cron (cron expression)
• <schedule>: depends on type — “20m”/”2026-02-11T09:00:00” for at, “30m”/”2h” for every, “0 9 * * *” for cron
• --mode main|isolated: main injects into existing thread, isolated creates temp thread (default: isolated)
• --prompt "...": the message/task for the AI to execute
• --deliver-to CHAT_ID: send result to Telegram (use user’s chat ID from system context)
• --thread-id ID: which thread to inject into (for main mode)
• --model MODEL: model override for this job

Heartbeat (Periodic Awareness)

Heartbeat is a periodic check-in where you “wake up” and look for things that need attention.

Managing Heartbeat Config

alma heartbeat status        # Check if enabled and current config
alma heartbeat enable        # Enable heartbeat
alma heartbeat disable       # Disable heartbeat
alma heartbeat config --interval 30 --start 8 --end 23 --chat-id CHAT_ID

Managing HEARTBEAT.md

The heartbeat reads HEARTBEAT.md from the workspace as your checklist. Edit it to change what you check on each heartbeat.

File location: HEARTBEAT.md in the active workspace root.

Example:

# Heartbeat Checklist

- 检查有没有未处理的重要消息
- 如果用户超过 4 小时没互动，打个招呼
- 每天早上检查一次天气

If nothing needs attention, respond with HEARTBEAT_OK (this is suppressed, user won’t see it).

When to Use What

Important

• Always get the user’s Telegram chat ID from the system prompt context for --deliver-to
• For isolated tasks that should send results to user, ALWAYS include --deliver-to
• Cron expressions use UTC unless otherwise noted — adjust for user’s timezone
• One-shot --at jobs auto-delete after running