cron-task

Overview

Create scheduled tasks that run an agent or script on a recurring schedule and deliver results to a messaging platform (Telegram, Discord, Slack, email). The task runs autonomously — no human needs to be present.

When to Use

• The user wants a recurring task (daily summary, weekly report, hourly check).
• The user wants to be notified on a schedule (server health check, price alert, feed monitor).
• The user says "run this every day", "schedule a task", "check this hourly", or "send me a daily summary".

Schedule Syntax

Three formats are supported:

Cron fields (5 fields, minute-level granularity):

┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-6, Sunday=0)
0 9 * * *   → every day at 9 AM
*/30 * * * * → every 30 minutes
0 9 * * 1   → every Monday at 9 AM
0 0 1 * *   → first of every month at midnight

Task Types

Agent-driven tasks: the scheduler runs the agent with the given prompt. The agent has tool access (web, terminal, file) and produces a response that gets delivered.

Script-only tasks: the scheduler runs a script (bash or Python). The script's stdout is delivered verbatim. No agent, no tokens, no model call. If the script produces no output, nothing is delivered (silent on no-news).

Delivery

Results are delivered to one or more messaging platforms:

The delivery includes a header identifying the job, the content, and a footer. The message is not mirrored into the target session — it's a one-way delivery that preserves session integrity.

Workflow

Step 1: Define the task

Confirm with the user:

• What should the task do? (the prompt or script)
• How often? (the schedule)
• Where should results go? (the delivery target)

Step 2: Create the job

Via the Hermes CLI:

hermes cron create "0 9 * * *" --prompt "Check server health and report any issues" --deliver telegram

Via the cronjob tool (in-session):

cronjob(action="create", schedule="0 9 * * *", prompt="Check server health and report any issues", deliver="telegram")

Step 3: Script-only task (if no agent needed)

cronjob(
    action="create",
    schedule="*/30m",
    script="scripts/health_check.py",
    no_agent=True,
    deliver="telegram"
)

The script runs every 30 minutes. Non-empty stdout is delivered. Empty stdout = silent (nothing sent). Non-zero exit = error alert sent.

Step 4: Chain jobs (optional)

One job's output can feed into another:

cronjob(
    action="create",
    schedule="0 6 * * *",
    prompt="Collect overnight metrics and summarize",
    name="metrics-collector"
)

cronjob(
    action="create",
    schedule="0 9 * * *",
    prompt="Write a daily briefing from the collected metrics",
    context_from=["metrics-collector"],
    deliver="telegram"
)

The second job receives the first job's most recent output as context.

Step 5: Verify

hermes cron list          # see all jobs
hermes cron run <id>      # trigger immediately for testing

Common Patterns

Common Pitfalls

1. Silent failures on bad output, not just bad exit codes. A script that crashes with a non-zero exit code sends an error alert. But a script that runs successfully and produces wrong output won't alert anyone. Test scripts manually before scheduling them.
2. Hitting platform rate limits. A task running every minute that sends a message every time will hit Telegram's rate limit within an hour. Only deliver when there's something to say — use the silent-on-no-news pattern.
3. Long-running tasks get killed. There's a 3-minute hard interrupt per run. If your prompt or script takes longer, it gets killed mid-run. Break long work into chunks or use a background process instead.
4. Timezone confusion in cron expressions. Cron expressions run in the host's local timezone by default, not UTC and not the user's timezone. Confirm the timezone with the user if the schedule needs to land at an exact wall-clock time.
5. Fighting the duplicate-tick lock. A lock file prevents duplicate runs across processes. Don't try to work around it — if a tick is locked, the previous run is still in progress, not stuck.
6. Delivering to a misconfigured target. The delivery target must already be configured in the gateway. A target that doesn't exist fails silently — verify the platform/channel is reachable before scheduling, not after the first missed delivery.
7. Context bloat in chained jobs. context_from injects the full output of the upstream job into the downstream prompt. If the upstream produces a large report, the downstream job's prompt gets inflated every run. Keep upstream outputs concise by design.

Verification Checklist

• hermes cron run <id> was used to trigger the job once manually and confirmed it delivers correctly before relying on the schedule
• Script-only jobs were tested standalone (python scripts/health_check.py) to confirm stdout behavior on both success and failure
• Delivery target (Telegram chat, Discord channel, etc.) is already configured in the gateway, not just assumed to exist
• Schedule's timezone matches what the user expects (confirmed, not assumed to be UTC or local)
• hermes cron list shows the new job with the correct schedule string
• Chained jobs' upstream output is short enough not to bloat the downstream prompt on every run