crondex

  ______________  ____  ____/ /__  _  __
 / ___/ ___/ __ \/ __ \/ __  / _ \| |/_/
 / /__/ /  / /_/ / / / / /_/ /  __/>  <
 \___/_/   \____/_/ /_/\__,_/\___/_/|_|

Works with Claude, Codex, Hermes, OpenClaw, or any plain LLM with shell access.

Get a job

npx @wonsukchoi/crondex recommend "warn me before my SSL cert expires"
npx @wonsukchoi/crondex show ssl-cert-expiry-check
npx @wonsukchoi/crondex deploy ssl-cert-expiry-check --var host=example.com

• recommend "<what you want>" — find the closest matching job (zero tokens, no network call, so an agent can check before writing one from scratch). Matching handles plurals, a small catalog-grounded synonym set (e.g. "notify"/"warn"/"remind" all match jobs tagged reminder), and falls back to fuzzy (edit-distance) matching on typos when nothing matches exactly.
• list [--category x] [--tag y] / categories — browse everything
• show <id> — print a job's full YAML
• next <id> [--count n] — print the next N run times for a job's schedule, in its declared timezone (zero tokens, no network call) — sanity-check a schedule before deploying it
• add <id> [--dest path] — copy it into your project to edit
• init <id> [--category x] — scaffold a brand-new job from the template
• update <path> [--dry-run] — re-pull a job you already added/inited (matched by its id field) against the current catalog, print a diff of what changed, and overwrite it in place. --dry-run shows the diff without applying it.
• deploy <id> --target <crontab|github-actions|systemd|docker|k8s-cronjob|terraform|nomad|eventbridge|cloud-scheduler> [--var name=value ...] — turn a job into something that actually runs (crontab line, GitHub Actions workflow, systemd timer, Dockerfile, k8s CronJob, Terraform kubernetes_cron_job_v1 resource, or a ready aws/gcloud command). --var overrides a variable's default. hybrid jobs deploy command by default; add --mode prompt for the prompt side.
• deploy --list-installed — show every crondex-managed line in your crontab (the ones left by --install)
• uninstall <id> — remove one of those installed crontab entries
• doctor [--json] — audit installed crontab entries against the catalog: orphaned entries, schedule drift, and version tagging/staleness. Exits 1 if any issues were found.
• bundle <file.yaml> [--target <target>] [--dry-run] [--out-dir <path>] [--install] — deploy every job in a manifest in one shot (see Bundles)

Add --json to list/categories/show/recommend for machine-readable output — useful when an agent is parsing the result programmatically instead of a human reading it.

No install needed — npx always runs against the latest catalog.

Use as an MCP server

Skip the shell-out entirely — register crondex as an MCP server and your agent gets recommend/list/categories/show/next as native tools instead of invoking a CLI. Read-only: no filesystem writes, no crontab access.

Claude Code:

claude mcp add crondex -- npx -y @wonsukchoi/crondex mcp

Any other MCP client (e.g. .mcp.json, Claude Desktop's config):

{
  "mcpServers": {
    "crondex": {
      "command": "npx",
      "args": ["-y", "@wonsukchoi/crondex", "mcp"]
    }
  }
}

Tools exposed: crondex_recommend, crondex_list, crondex_categories, crondex_show, crondex_next_runs — each returns the same JSON shape as the matching CLI command's --json flag.

Pass --allow-deploy (crondex mcp --allow-deploy, or add it to your MCP client's args) to opt into one more tool: crondex_deploy. It takes the same inputs as crondex deploy (id, target, vars, mode) and returns the generated artifact text — a crontab line, workflow file, systemd unit pair, etc. It's generation-only: it never writes a file, never touches your crontab, and has no other side effect, so the server stays safe to point an agent at even with --allow-deploy on. Without the flag, crondex_deploy isn't registered at all.

What's in a job

Every job is one YAML file:

id: dependency-audit
version: 1
name: Dependency Vulnerability Audit
category: devops
schedule: "0 8 * * 1"    # standard 5-field cron
runner: hybrid            # shell | agent-prompt | hybrid
command: |                 # for runner: shell/hybrid
  ...raw shell audit, zero tokens...
prompt: |                  # for runner: agent-prompt/hybrid
  ...instructions with {{repo_path}}, LLM synthesizes+prioritizes...
script_note: what you lose by using `command` instead of `prompt`
variables:
  repo_path:
    default: "."
compatible_agents: [claude, codex, hermes, openclaw, generic]

• shell — runs command only. Zero LLM tokens, deterministic.
• agent-prompt — hands prompt to an LLM each run. Costs tokens, but can synthesize, prioritize, and draft prose.
• hybrid — ships both, pick per run: script to save tokens, prompt for more judgment. script_note explains the tradeoff.

{{placeholders}} resolve from variables — override them for your case, then hand command/prompt plus schedule to whatever scheduler you have (system crontab, a hosted cron, your agent's own scheduling mechanism). This repo defines what to run and when, not the executor. Full field spec: schema/job.schema.json.

Bundles

Deploy several jobs in one shot with a manifest file:

# bundle.yaml
jobs:
  - id: ssl-cert-expiry-check
    vars:
      host: example.com
      port: "443"
  - id: dependency-audit
    vars:
      repo_path: /srv/app
  - id: cost-alert
    mode: prompt

crondex bundle bundle.yaml --target crontab --dry-run   # preview
crondex bundle bundle.yaml --target crontab --install   # install every job
crondex bundle bundle.yaml --target github-actions --out-dir .github/workflows

Each entry supports id (required), vars (variable overrides, same shape as deploy --var), and mode (script/prompt, for hybrid jobs). --target crontab (the default) combines every job into one crontab line per job; every other target either writes one file (or file pair, for systemd/docker) per job to --out-dir, or — without --out-dir — prints all the artifacts concatenated with === header separators. --dry-run previews the combined output without installing or writing anything.

Browse the catalog

The table below is regenerated by npm run build-catalog, so it never drifts from what's actually in jobs/. For full details (description, tags, variables) use crondex list, crondex recommend, or browse jobs/<category>/ directly.

2639 jobs across 66 categories (2251 smoke-tested clean):

Layout

crondex/
├── llms.txt               agent-discovery manifest (llms.txt convention)
├── bin/crondex.js         thin CLI entry point — parsing/routing lives in lib/cli.js
├── lib/                   cli, doctor, bundle, recommend, deploy, diff, and catalog-building logic (unit tested in test/)
├── catalog.json           generated index of every job — read this first
├── schema/job.schema.json spec every job file follows
├── jobs/                  one YAML per job, grouped by category subdirectory
└── scripts/               build-catalog.js, validate-jobs.js, lint-shell.js, check-duplicates.js, smoke-test.js

Contributing a job

See CONTRIBUTING.md — copy templates/job.template.yaml (or run crondex init), fill it in, npm run validate && npm run build-catalog, open a PR. If you're touching JS in bin/, lib/, scripts/, or test/, run npm run format and npm run lint (Biome) — CI runs the same lint check. See ROADMAP.md for what's prioritized right now and what's deliberately not built yet.

License

MIT