---
sidebar_position: 11
title: "Cron Internals"
description: "How Hermes stores, schedules, edits, pauses, skill-loads, and delivers cron jobs"
---

# 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.

## Related docs

- [Cron feature guide](../user-guide/features/cron.md)
- [Gateway Internals](./gateway-internals.md)