Skip to content

itpartypattaya/hermes-cron

v1.5.4MIT

Operating skill for Hermes cron jobs: create, change, pause and debug them safely, with a read-only doctor.

hermes-cron

hermes-cron — safe cron jobs for Hermes Agent

A skill that teaches Hermes Agent to run its cron scheduler like a careful operator: pick the right lifecycle action, keep jobs cheap and quiet, verify every change and find the broken layer when a reminder does not arrive. It ships with a read-only doctor script that complements the built-in hermes cron doctor.

Why

Cron failures in an agent look like success. The tool answers success: true, the record says paused, last_status is ok — and the messages keep coming, or never arrive. Typical causes:

  • a bare 30m was meant as "in 30 minutes" but schedules a job every 30 minutes;
  • the prompt says "send a summary", so the agent sends it and the scheduler delivers it again;
  • deliver: origin points at the chat where the job was created, not at the person it is for;
  • a record with enabled: true and a pause marker never fires, yet the list shows it as scheduled;
  • a pinned model ignores hermes model and skips the fallback chain when its provider is down.

The skill turns each of these into a rule the agent follows, and the doctor makes them visible.

What you get

PartWhat it does
SKILL.mdWhen to use, lifecycle table, cheap modes, procedure, pitfalls, verification
scripts/cron-doctor.pyRead-only health check: scheduler, jobs, delivery, incidents
references/reference.mdCLI, cronjob tool fields, schedules, statuses, markers, cron: settings
references/troubleshooting.mdSymptom runbook: missed, late, duplicated, misrouted, silent jobs

Wake the model only when needed

Four ways a cron job avoids a needless LLM run

SituationModeHow it stays silent
Text is known in advance; alert watchdogno_agent: true + scriptempty stdout or {"wakeAgent": false}
Fresh data needed, real work is rarescript pre-checklast line {"wakeAgent": false}
"Tell me when this changes"monitor (script or URL)unchanged output skips the agent run
The model decides, but not always reportsLLM jobreply exactly [SILENT]

Debug by layers

Check the scheduler, the job record, the execution, the delivery and other writers in that order

When a job misbehaves, the skill walks the layers top to bottom instead of rewriting the schedule: is the scheduler ticking, is the record consistent, was there an attempt, was the result delivered, and did a sync or deployment overwrite the change.

Install

Pick one. Option 1 is the usual choice: the skill lands in ~/.hermes/skills/ and the agent picks it up from its description.

1. As a regular skill (recommended)

hermes skills install itpartypattaya/hermes-cron/skills/hermes-cron

2. As a portable plugin (Agent Plugins v1 package: plugin.json + skills/)

hermes plugins install itpartypattaya/hermes-cron --no-enable
hermes plugins enable hermes-cron

Plugin skills are read-only and namespaced. They are not listed in the system prompt; the agent finds them through skills_list and loads them with skill_view.

3. Manually

git clone https://github.com/itpartypattaya/hermes-cron.git
cp -r hermes-cron/skills/hermes-cron ~/.hermes/skills/

Use it

Ask the agent in plain words; the skill covers the rest.

  • "Remind me in 30 minutes to call the bank." → a one-shot in 30m, verified, with the exact time.
  • "Pause the morning digest until Monday." → pause, plus who resumes it on Monday — Hermes has no scheduled resume for recurring jobs — and no new duplicate job.
  • "Ping me only if the disk is over 90 %." → a script-only watchdog, tested for silence and for alert.
  • "Why didn't the 9 am report arrive?" → doctor first, then the layer that broke, then the fix.

The doctor

python3 ~/.hermes/skills/hermes-cron/scripts/cron-doctor.py              # all jobs
python3 ~/.hermes/skills/hermes-cron/scripts/cron-doctor.py --job <id>   # one job + recent runs
python3 ~/.hermes/skills/hermes-cron/scripts/cron-doctor.py --json       # for automation
python3 ~/.hermes/skills/hermes-cron/scripts/cron-doctor.py --no-builtin # skip `hermes cron doctor`
python3 ~/.hermes/skills/hermes-cron/scripts/cron-doctor.py --profile work # jobs of a named profile

Inside the skill the path is "${HERMES_SKILL_DIR}/scripts/cron-doctor.py", so it works wherever the skill is installed. The doctor runs the built-in hermes cron doctor when the CLI is found (PATH, ~/.local/bin or HERMES_BIN) and adds what it does not check:

  • ticker heartbeat and last successful tick, with the PID that wrote the stamp, and the error of a failed tick (ticker_last_error);
  • a one-line count of jobs by state (summary in --json);
  • disabled, paused and half-paused jobs — the built-in check looks at active jobs only;
  • duplicate ids, malformed entries, unknown schedule kinds, no_agent without a script, failure streaks;
  • the delivery outcome of each job's latest completed run and open failure incidents from executions.db (ordered by the real instant, not by timestamp text);
  • the same error in three or more jobs within 24 hours, reported once as a scheduler or host fault (shared_failures in --json). Per-job fields hide it: they reset on the next good run, and a failed dispatch may open no incident at all. Run ids, timestamps, measured durations and PIDs are masked before grouping; interruptions by a gateway restart are not counted;
  • pinned models and thread-less delivery into chats that use threads;
  • a cron store this user cannot write, or one with less than 100 MB free: Hermes 0.21.6+ skips due jobs it cannot record. The check reads permission bits and free space and creates no file;
  • the sticky last_failure (0.21.6+) of a job that has recovered since, as a note;
  • a pause Hermes 0.22.4+ set itself after a fire it could not verify — resuming it by hand before reading hermes cron runs <id> may run the job twice;
  • agent jobs that a headless hermes cron tick skipped because no gateway was ready: two or more are one fault (skipped_fires in --json), and their overdue slots are not reported one by one;
  • a delivery still queued an hour after its run (0.22.4+ writes the outcome back once the gateway drains), as a note;
  • a bot-chat:<profile> delivery parked until the target profile runs, which Hermes books as delivery_failed, as a note instead of "not delivered";
  • a script that is a shell command line (echo hi), which 0.22.4+ refuses on create and update.

Without the CLI, and always for --job, it performs the basic checks itself: failed last run, undelivered result, a missing or overdue next_run_at, a failed dispatch, a script outside the scripts directory or missing (with a hint when it is a command line), a missing working directory. A built-in doctor that crashes, or a run history that exists but cannot be read, is a finding, not a note. Exit codes: 0 healthy, 1 findings (--job included), 2 unreadable runtime state, 3 invalid arguments or an unknown job; with --json, errors are JSON too.

== Scheduler ==
  heartbeat: 12 s ago, PID 41873
  successful tick: 12 s ago

== Built-in hermes cron doctor ==
  ✓ Cron doctor found no issues
    Checked 5 active job(s).

== Jobs ==
  7 total · 4 enabled · 1 half-paused · 1 paused · 1 completed
  …

== Findings ==
  🔴 3f2a9c1d7e44 "Weekly report": enabled=true with a pause marker — Hermes will not run it,
     yet `cron list` shows it as scheduled; pause or resume it properly

== Notes ==
  ℹ️ 8b1e6d0a2f93 "Nightly digest": pinned model (model-x · provider-y) — does not follow
     `hermes model` and does not use the global fallback chain

Safety and privacy

  • Read-only. The doctor never ticks, runs, edits or removes a job.
  • No network access and no API keys. The only subprocess is the local hermes cron doctor, started as an argument list without a shell. Hermes' own job loader, like every scheduler tick, may repair malformed entries in jobs.json.
  • It reads ~/.hermes/cron/jobs.json, the ticker stamps and executions.db (opened read-only). It writes nothing and does not read the gateway's admission journals or parked deliveries. Like any SQLite reader of a WAL database it may create the -shm/-wal files Hermes itself uses; without write access to cron/ it reads the main file without locks and says so in its notes. A database that is locked by a writer is reported as unreadable, not read around.
  • The skill registers no tools, hooks or middleware and needs no environment variables.

Compatibility

Written against Hermes Agent 0.21.5 and checked against 0.21.6, 0.22.0, 0.22.2, 0.22.4 and 0.22.5:

  • in 30m is one-shot; 30m and every 30m repeat; every monday 9am and weekdays at 9am become cron expressions;
  • jobs follow cron.model or the main model at fire time unless pinned;
  • since 0.21.6, enabled_toolsets: [] means a job with no tools, not the default set; a restricted job goes back to the default set through the web dashboard or by recreating it;
  • the agent tool is cronjob_manage (old name cronjob) and is loaded on demand through tool_search;
  • one gateway serves every profile; a named profile's jobs live in ~/.hermes/profiles/<name>/ — --profile <name> points the doctor there;
  • a job runs only when enabled is true and it carries no pause marker;
  • the ticker heartbeat is <epoch> <pid> (older <epoch> stamps are still read);
  • since 0.22.4 agent jobs run through the gateway that owns the store: hermes cron tick from an external scheduler runs only no_agent jobs while no gateway is ready, and a fire Hermes cannot verify pauses the job until it is reconciled;
  • since 0.22.4 script must be a file under scripts/; a command line is refused.

On an older Hermes, check flags with hermes cron create --help before following the examples.

Scope

The skill covers the standard Hermes cron contract and assumes no repository, user, chat, timezone or delivery target. GitOps snapshots, three-way merges, persistent configuration and organization-specific alert routing are out of scope; keep them in a separate local skill loaded alongside this one.

Repository layout

plugin.json                      # Agent Plugins v1 manifest
skills/hermes-cron/
  SKILL.md
  scripts/cron-doctor.py
  references/reference.md
  references/troubleshooting.md
tests/test_cron_doctor.py        # stdlib unittest, no network
contract/test_core_contract.py   # the doctor on a store real Hermes core wrote
docs/                            # images used by this README

Development

python3 -m unittest discover -s tests -v

The unit tests build jobs.json and executions.db by hand. CI also runs contract/ against the latest Hermes release: the core itself creates, pauses and runs no-agent jobs, and the doctor must read that store with no false findings and with every planted fault found. Locally it needs Hermes core installed in the same Python:

python3 -m unittest discover -s contract -v

Issues and pull requests are welcome.

Author

Anton Vaskov — Telegram @passone, GitHub itpartypattaya.

License

MIT