SKILL.md
Agent Self-Scheduling
When to Use
- Use when the user asks for recurring, scheduled, heartbeat, or looped agent work.
- Use when you need to choose between cron, external schedulers, hooks, or built-in agent scheduling.
First question: does the agent have a built-in scheduler (Hermes → Camp B), or do you own the clock (everything else → Camp A)?
Universal floor: cron is 1 minute minimum (5-field expr, no seconds) — every camp. For sub-minute you MUST use a while ...; sleep N; done loop, a TS extension, or an event hook. Never put an LLM on a tight timer.
Camp A — one-shot agents, you own the clock
These run once and exit (amnesiac unless resumed). Schedule them externally.
claude -p "PROMPT" --output-format json --allowedTools "Read,Edit,Bash" # Claude Code
codex exec --json "PROMPT" # Codex
pi run "PROMPT" # Pi
Wrap in a clock:
# 1. cron (>= 1 min floor)
*/10 * * * * cd /path/to/project && pi run "check X and report" >> ~/agent.log 2>&1
# 2. systemd timer (Linux, survives reboot, better logging) — OnUnitActiveSec=10min
# 3. dumb loop (sub-minute, or no cron available)
while true; do pi run "check X"; sleep 30; done
Gotchas (each breaks unattended runs if ignored):
- Permissions hang forever. Pass
--allowedTools(Claude) or sandbox/auto-approve flags (Codex), or the run blocks on a prompt. - Use JSON output (
--output-format json/--json) so the wrapper parses results deterministically. - Runs are amnesiac. Resume (
codex exec resume --last) or persist state to a file the next run reads.
Pi has NO built-in scheduler/loop/heartbeat by design — external clock only (or a TS extension for agent-side timers).