crondex

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

Funciona com Claude, Codex, Hermes, OpenClaw ou qualquer LLM simples com acesso ao shell.

Obter uma tarefa

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>" — encontra a tarefa mais próxima (zero tokens, sem chamada de rede, para que um agente possa verificar antes de escrever uma do zero). A correspondência lida com plurais, um pequeno conjunto de sinônimos baseado no catálogo (ex.: "notify"/"warn"/"remind" todos correspondem a tarefas marcadas com reminder), e recorre a correspondência difusa (distância de edição) para erros de digitação quando nada corresponde exatamente.
• list [--category x] [--tag y] / categories — navegar por tudo
• show <id> — imprime o YAML completo de uma tarefa
• next <id> [--count n] — imprime os próximos N horários de execução para o agendamento de uma tarefa, no fuso horário declarado (zero tokens, sem chamada de rede) — verifique a sanidade de um agendamento antes de implantá-lo
• add <id> [--dest path] — copia para o seu projeto para editar
• init <id> [--category x] — cria uma nova tarefa a partir do modelo
• update <path> [--dry-run] — re-puxa uma tarefa que você já addou/initou (correspondida pelo campo id) contra o catálogo atual, imprime um diff do que mudou e a sobrescreve no lugar. --dry-run mostra o diff sem aplicá-lo.
• deploy <id> --target <crontab|github-actions|systemd|docker|k8s-cronjob|terraform|nomad|eventbridge|cloud-scheduler> [--var name=value ...] — transforma uma tarefa em algo que realmente executa (linha de crontab, workflow do GitHub Actions, timer do systemd, Dockerfile, CronJob do k8s, recurso kubernetes_cron_job_v1 do Terraform ou um comando aws/gcloud pronto). --var substitui o padrão de uma variável. Tarefas hybrid implantam command por padrão; adicione --mode prompt para o lado do prompt.
• deploy --list-installed — mostra todas as linhas gerenciadas pelo crondex no seu crontab (as deixadas por --install)
• uninstall <id> — remove uma dessas entradas de crontab instaladas
• doctor [--json] — audita entradas de crontab instaladas contra o catálogo: entradas órfãs, desvio de agendamento e versionamento/obsolescência. Sai com 1 se algum problema for encontrado.
• bundle <file.yaml> [--target <target>] [--dry-run] [--out-dir <path>] [--install] — implanta todas as tarefas de um manifesto de uma só vez (veja Bundles)

Adicione --json a list/categories/show/recommend para saída legível por máquina — útil quando um agente está analisando o resultado programaticamente em vez de um humano lê-lo.

Sem necessidade de instalação — npx sempre executa contra o catálogo mais recente.

Usar como servidor MCP

Pule completamente a chamada de shell — registre o crondex como um servidor MCP e seu agente obtém recommend/list/categories/show/next como ferramentas nativas em vez de invocar uma CLI. Somente leitura: sem gravações no sistema de arquivos, sem acesso ao crontab.

Claude Code:

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

Qualquer outro cliente MCP (ex.: .mcp.json, config do Claude Desktop):

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

Ferramentas expostas: crondex_recommend, crondex_list, crondex_categories, crondex_show, crondex_next_runs — cada uma retorna o mesmo formato JSON que o comando CLI correspondente com a flag --json.

Passe --allow-deploy (crondex mcp --allow-deploy, ou adicione-o aos argumentos do seu cliente MCP) para optar por mais uma ferramenta: crondex_deploy. Ela recebe as mesmas entradas que crondex deploy (id, target, vars, mode) e retorna o texto do artefato gerado — uma linha de crontab, arquivo de workflow, par de unidades do systemd, etc. É somente geração: nunca grava um arquivo, nunca toca no seu crontab e não tem outro efeito colateral, então o servidor permanece seguro para apontar um agente mesmo com --allow-deploy ativado. Sem a flag, crondex_deploy não é registrado de forma alguma.

O que há em uma tarefa

Cada tarefa é um arquivo 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 — executa command apenas. Zero tokens de LLM, determinístico.
• agent-prompt — entrega prompt a um LLM a cada execução. Custa tokens, mas pode sintetizar, priorizar e redigir prosa.
• hybrid — inclui ambos, escolha por execução: script para economizar tokens, prompt para mais julgamento. script_note explica o trade-off.

{{placeholders}} resolvem a partir de variables — substitua-os para o seu caso, depois entregue command/prompt mais schedule para qualquer agendador que você tenha (crontab do sistema, um cron hospedado, o mecanismo de agendamento do seu próprio agente). Este repositório define o que executar e quando, não o executor. Especificação completa dos campos: schema/job.schema.json.

Bundles

Implante várias tarefas de uma só vez com um arquivo de manifesto:

# 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 suporta id (obrigatório), vars (substituições de variáveis, mesma forma que deploy --var) e mode (script/prompt, para tarefas hybrid). --target crontab (o padrão) combina cada tarefa em uma linha de crontab por tarefa; todo outro destino ou grava um arquivo (ou par de arquivos, para systemd/docker) por tarefa em --out-dir, ou — sem --out-dir — imprime todos os artefatos concatenados com separadores de cabeçalho ===. --dry-run pré-visualiza a saída combinada sem instalar ou gravar nada.

Navegar pelo catálogo

A tabela abaixo é regenerada por npm run build-catalog, então ela nunca se desvia do que realmente está em jobs/. Para detalhes completos (descrição, tags, variáveis) use crondex list, crondex recommend ou navegue por jobs/<category>/ diretamente.

2639 tarefas em 66 categorias (2251 testadas e limpas):

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

Contribuindo com um job

Veja CONTRIBUTING.md — copie templates/job.template.yaml (ou execute crondex init), preencha, npm run validate && npm run build-catalog, open a PR. If you're touching JS in bin/, lib/, scripts/, ou test/, execute npm run format e npm run lint (Biome) — o CI executa a mesma verificação de lint. Veja ROADMAP.md para saber o que está priorizado no momento e o que deliberadamente ainda não foi construído.

Licença

MIT