Skip to main content

Cron Internals

Hermes cron support is implemented primarily in:

  • cron/jobs.py
  • cron/scheduler.py
  • tools/cronjob_tools.py
  • gateway/run.py
  • hermes_cli/cron.py

Scheduling model​

Hermes supports:

  • one-shot delays
  • intervals
  • cron expressions
  • explicit timestamps

The model-facing surface is a single cronjob tool with action-style operations:

  • create
  • list
  • update
  • pause
  • resume
  • run
  • remove

Job storage​

Cron jobs are stored in Hermes-managed local state (~/.hermes/cron/jobs.json) with atomic write semantics.

Each job can carry:

  • prompt
  • schedule metadata
  • repeat counters
  • delivery target
  • lifecycle state (scheduled, paused, completed, etc.)
  • zero, one, or multiple attached skills

Backward compatibility is preserved for older jobs that only stored a legacy single skill field or none of the newer lifecycle fields.

Runtime behavior​

The scheduler:

  • loads jobs
  • computes due work
  • executes jobs in fresh agent sessions
  • optionally injects one or more skills before the prompt
  • handles repeat counters
  • updates next-run metadata and state

In gateway mode, cron ticking is integrated into the long-running gateway loop.

Skill-backed jobs​

A cron job may attach multiple skills. At runtime, Hermes loads those skills in order and then appends the job prompt as the task instruction.

This gives scheduled jobs reusable guidance without requiring the user to paste full skill bodies into the cron prompt.

Recursion guard​

Cron-run sessions disable the cronjob toolset. This prevents a scheduled job from recursively creating or mutating more cron jobs and accidentally exploding token usage or scheduler load.

Delivery model​

Cron jobs can deliver to:

  • origin chat
  • local files
  • platform home channels
  • explicit platform/chat IDs

Locking​

Hermes uses lock-based protections so overlapping scheduler ticks do not execute the same due-job batch twice.