croncron AGENTS.md

croncron — agent guide

You (an AI agent) can manage this machine's cron jobs with croncron. Two interfaces:

1. MCP (preferred when available)

Server: croncron mcp (stdio). Tools: cron_add, cron_list, cron_edit, cron_remove, cron_pause, cron_run_now, cron_logs, cron_catchup.

Register in Claude Code: claude mcp add --scope user croncron -- croncron mcp

2. CLI with --json (any shell-capable agent)

Every read/write command accepts --json and prints machine-readable JSON:

croncron add "every 10 minutes" "curl -s https://example.com/ping" --json
croncron add "daily at 3am" ./backup.sh --retry 2 --ping https://hc-ping.com/UUID --json
croncron list --json          # nextRun, lastRun {code,ms}, missedLastScheduledRun per job
croncron run <name> --json    # {exitCode, ms, output}
croncron runs <name> --json   # run history
croncron edit <name> --schedule "weekdays at 9am" --json
croncron rm <name> --json

Errors go to stderr as {"ok":false,"error":"..."} with exit code 1.

Things agents should know

• Schedules: plain English ("every 5 minutes", "weekdays at 9:30", "monthly on the 1st at 9am") or raw 5-field cron. Both validated; bad input fails loudly with examples.
• Output is captured automatically — never append >> file 2>&1 to commands.
• cwd/PATH/shell are snapshotted at add time — add jobs from the project directory they should run in, or pass --cwd.
• Verify your work: after add, run croncron run <name> --json once and check exitCode: 0.
• Failures alert the user (macOS notification / Telegram) once per state change. Use --no-notify for noisy experimental jobs.
• Reliability built in: --retry N re-attempts failures; overlapping runs are skipped; the watchdog re-runs jobs missed while the laptop slept (croncron watchdog status).
• Never edit the crontab directly — croncron owns a marked block; everything else in the user's crontab is preserved and backed up to ~/.croncron/backups/.