crondex

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

Funciona con Claude, Codex, Hermes, OpenClaw, o cualquier LLM con acceso a shell.

Obtener un trabajo

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>" — encuentra el trabajo que mejor coincida (cero tokens, sin llamada de red, para que un agente pueda verificar antes de escribir uno desde cero). La coincidencia maneja plurales, un pequeño conjunto de sinónimos basado en el catálogo (p. ej., "notify"/"warn"/"remind" coinciden con trabajos etiquetados como reminder), y recurre a coincidencia difusa (distancia de edición) para errores tipográficos cuando nada coincide exactamente.
• list [--category x] [--tag y] / categories — explorar todo
• show <id> — imprime el YAML completo de un trabajo
• next <id> [--count n] — imprime las próximas N horas de ejecución para el horario de un trabajo, en su zona horaria declarada (cero tokens, sin llamada de red) — verifica un horario antes de implementarlo
• add <id> [--dest path] — cópialo en tu proyecto para editarlo
• init <id> [--category x] — genera un trabajo nuevo desde la plantilla
• update <path> [--dry-run] — vuelve a extraer un trabajo que ya added/inited (coincidido por su campo id) contra el catálogo actual, imprime un diff de lo que cambió, y sobrescríbelo en su lugar. --dry-run muestra el diff sin aplicarlo.
• deploy <id> --target <crontab|github-actions|systemd|docker|k8s-cronjob|terraform|nomad|eventbridge|cloud-scheduler> [--var name=value ...] — convierte un trabajo en algo que realmente se ejecute (línea de crontab, flujo de trabajo de GitHub Actions, temporizador systemd, Dockerfile, CronJob de k8s, recurso kubernetes_cron_job_v1 de Terraform, o un comando aws/gcloud listo). --var anula el valor predeterminado de una variable. Los trabajos hybrid se implementan command por defecto; agrega --mode prompt para el lado del prompt.
• deploy --list-installed — muestra cada línea gestionada por crondex en tu crontab (las dejadas por --install)
• uninstall <id> — elimina una de esas entradas de crontab instaladas
• doctor [--json] — audita las entradas de crontab instaladas contra el catálogo: entradas huérfanas, desviación de horario, y etiquetado/obsolescencia de versiones. Sale con 1 si se encontraron problemas.
• bundle <file.yaml> [--target <target>] [--dry-run] [--out-dir <path>] [--install] — implementa cada trabajo en un manifiesto de una sola vez (ver Bundles)

Agrega --json a list/categories/show/recommend para salida legible por máquina — útil cuando un agente analiza el resultado programáticamente en lugar de que un humano lo lea.

No se necesita instalación — npx siempre se ejecuta contra el catálogo más reciente.

Usar como servidor MCP

Omite el shell por completo — registra crondex como servidor MCP y tu agente obtiene recommend/list/categories/show/next como herramientas nativas en lugar de invocar una CLI. Solo lectura: sin escrituras en el sistema de archivos, sin acceso a crontab.

Claude Code:

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

Cualquier otro cliente MCP (p. ej., .mcp.json, la configuración de Claude Desktop):

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

Herramientas expuestas: crondex_recommend, crondex_list, crondex_categories, crondex_show, crondex_next_runs — cada una devuelve la misma forma JSON que el indicador --json del comando CLI correspondiente.

Pasa --allow-deploy (crondex mcp --allow-deploy, o agrégalo a los argumentos de tu cliente MCP) para optar por una herramienta más: crondex_deploy. Toma las mismas entradas que crondex deploy (id, target, vars, mode) y devuelve el texto del artefacto generado — una línea de crontab, archivo de flujo de trabajo, par de unidades systemd, etc. Es solo generación: nunca escribe un archivo, nunca toca tu crontab, y no tiene otro efecto secundario, por lo que el servidor sigue siendo seguro para apuntar a un agente incluso con --allow-deploy activado. Sin el indicador, crondex_deploy no se registra en absoluto.

Qué contiene un trabajo

Cada trabajo es un archivo YAML:

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 — ejecuta command solamente. Cero tokens de LLM, determinista.
• agent-prompt — entrega prompt a un LLM en cada ejecución. Cuesta tokens, pero puede sintetizar, priorizar y redactar prosa.
• hybrid — incluye ambos, elige por ejecución: script para ahorrar tokens, prompt para más criterio. script_note explica el equilibrio.

{{placeholders}} se resuelven desde variables — anúlelos para tu caso, luego entrega command/prompt más schedule a cualquier programador que tengas (crontab del sistema, un cron alojado, el mecanismo de programación de tu propio agente). Este repositorio define qué ejecutar y cuándo, no el ejecutor. Especificación completa de campos: schema/job.schema.json.

Bundles

Implementa varios trabajos de una sola vez con un archivo de manifiesto:

# 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

Cada entrada admite id (obligatorio), vars (anulaciones de variables, misma forma que deploy --var), y mode (script/prompt, para trabajos hybrid). --target crontab (el predeterminado) combina cada trabajo en una línea de crontab por trabajo; cualquier otro destino escribe un archivo (o par de archivos, para systemd/docker) por trabajo en --out-dir, o — sin --out-dir — imprime todos los artefactos concatenados con separadores de encabezado ===. --dry-run previsualiza la salida combinada sin instalar ni escribir nada.

Explorar el catálogo

La tabla siguiente se regenera con npm run build-catalog, por lo que nunca se desvía de lo que realmente está en jobs/. Para detalles completos (descripción, etiquetas, variables) usa crondex list, crondex recommend, o explora jobs/<category>/ directamente.

2639 trabajos en 66 categorías (2251 probados limpios):

Diseño

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

Contribuir con un trabajo

Consulta CONTRIBUTING.md — copia templates/job.template.yaml (o ejecuta crondex init), complétalo, npm run validate && npm run build-catalog, open a PR. If you're touching JS in bin/, lib/, scripts/, o test/, ejecuta npm run format y npm run lint (Biome) — CI ejecuta la misma verificación de lint. Consulta ROADMAP.md para ver qué se prioriza actualmente y qué deliberadamente aún no se ha construido.

Licencia

MIT