cron-human: a human-readable cron CLI and MCP server

Key Takeaways

• cron-human translates cron expressions to plain English, computes next N runs in any timezone, diffs schedules, and estimates yearly cost.
• It ships as a CLI, a TypeScript library, and an MCP server — same primitives, three surfaces.
• 5,000+ npm downloads, MIT-licensed, zero-config: npx cron-human "*/5 * * * *".

If you've ever written a cron expression, you've also done this dance.

You type out something like 0 */4 * * 1-5, commit it, deploy it, and then three months later you're reading a config file trying to figure out why the hell a job is firing at a weird time. You open a new tab. You paste the expression into crontab.guru. You nod. You close the tab. You forget by Friday.

Cron is one of those pieces of infrastructure that's too simple to need documentation and too cryptic to read at a glance. It has survived since 1975 basically unchanged, which is a small miracle, but the tradeoff is that every developer who touches it ends up performing the same little ritual of translation, over and over again.

cron-human is my attempt to shorten that loop. It's an npm package (CLI plus library, plus an MCP server for AI agents) that lives in the gap between your terminal and your understanding of what a cron expression actually does. This post is about what it is, why it exists, and what I'm trying to build towards with it.

What does cron-human actually do?

cron-human takes a cron expression and tells you, in plain English, when it will run. It also tells you the next N times it will fire, handles timezones properly, supports seconds-precision, exposes a diff tool for comparing two expressions, a stats tool for estimating run frequency and cost, and ships with an interactive TUI for when you just want to poke around. There's also an MCP server so AI assistants can reason about cron expressions directly.

You can use it three ways:

# One-off, no install
npx cron-human "*/5 * * * *"

# Global install for the terminal
npm install -g cron-human

# As a library in your own project
npm install cron-human

That's the surface. The interesting part is what it's trying to be.

Why build another cron library?

There are existing libraries in this space. cronstrue has been around forever and does the core translation job well. crontab.guru is a beloved web tool. cron-parser handles the "when does this next fire" question at a library level. Each of them is good at one thing.

What I kept running into, as someone who uses cron in real systems, was that none of them were the thing I actually wanted in my terminal. I wanted one tool that could:

1. Explain the expression
2. Show me the next few runs in my actual timezone
3. Let me compare two expressions side by side when I'm refactoring a schedule
4. Give me a rough sense of how often something will fire over a year, and what that costs if each run has a price attached
5. Work as a CLI, as a library, and as an MCP tool for AI agents
6. Be installable with one command and usable with zero config

That's the brief. No part of it is novel on its own. The novelty, if there is one, is bundling all of it into a single tool with a consistent surface, so you don't have to context-switch between four packages and a web tab to answer one question about a scheduled job.

Which features matter most in practice?

Human descriptions

The core feature. Feed it a cron expression, get back an English sentence.

$ cron-human "*/15 9-17 * * 1-5"
Every 15 minutes, between 09:00 and 17:00, Monday through Friday

This handles the standard 5-field cron, the 6-field variant with seconds (via --seconds), and the common macros: @daily, @hourly, @weekly, @monthly, @yearly.

Next N runs, in your timezone

This is the feature I find myself using most. "When will this actually fire next, in a timezone I care about, as a real date I can read?"

$ cron-human "0 9 * * 1-5" --tz Europe/London --count 5

It prints the next five fire times in ISO format, formatted for the timezone you asked for. Default count is 5, max is 100. There's a --json flag if you're piping it into something else.

The timezone handling matters more than it sounds. If you're debugging a job that "runs at 9am" and your server is in UTC but you're in London during BST, the mental arithmetic is exactly the kind of thing you don't want to do under pressure.

diff: comparing two expressions

This one came out of a specific pain point. You're refactoring a schedule. You had 0 */6 * * * and you're changing it to 0 2,8,14,20 * * *. These look different but produce identical runs. Or they don't, and you want to know exactly where they diverge.

$ cron-human diff "0 */6 * * *" "0 2,8,14,20 * * *"

It shows both descriptions side by side and the first few runs from each, so you can eyeball whether they're equivalent or not. Cheap feature, saves an annoying amount of thinking.

stats: frequency and cost

For anyone running jobs on metered infrastructure, the question "how often does this actually fire, and what will it cost me over a year" is surprisingly hard to answer at a glance.

$ cron-human stats "*/5 * * * *" --cost-per-run 0.0001

It gives you runs per day, runs per month, runs per year, and (if you pass a per-run cost) the estimated yearly bill. It's not a replacement for proper cost monitoring, but for back-of-the-envelope decisions ("is this schedule reasonable?") it's faster than opening a calculator.

Interactive TUI

If you'd rather explore than remember flags, there's a TUI:

$ cron-human tui

Type an expression, see the description and next runs update live. Useful when you're building a schedule from scratch and iterating.

The MCP server: cron for agents

The part of this project I'm most interested in long-term is the MCP extension.

MCP (Model Context Protocol) is Anthropic's open standard for letting AI assistants call external tools. Once you wrap cron-human as an MCP server, any MCP-compatible agent, whether that's Claude Desktop, Claude Code, or a custom agent, can ask it questions directly.

The use case is immediate. Imagine you're in a chat with an agent and you say:

"Schedule a job to run every weekday at 9am London time except bank holidays, and tell me when it would next fire."

A general-purpose model can guess at the cron expression. With cron-human as an MCP tool, the agent can generate the expression, validate it, fetch the next five runs in the right timezone, and cost-model it against a given per-run price, all with proper tool calls instead of fabricated output.

This matters because cron is exactly the kind of structured-but-annoying domain where LLMs trip up. The syntax is small enough that they sort of know it, and big enough that they confidently get it wrong. Handing them a deterministic tool that does the parsing and calculation properly is a much better pattern than trusting them to do it in their heads.

The MCP server exposes the same primitives the CLI does: describe, next runs, stats, diff. The agent can chain them the way a developer would.

What design tradeoffs shaped cron-human?

A few decisions shaped the package more than the feature list suggests.

Zero config. The CLI works with no arguments beyond the expression itself. Timezone defaults to your system, count defaults to 5, output defaults to human-readable. Flags are available when you want them, absent when you don't. I wanted the thing you type at 11pm on a Friday to Just Work.

TypeScript first, but the library entry is lean. The package is written in TypeScript with typed exports, but the compiled dist/lib.js is small and has no heavy runtime dependencies. You can import { describe, nextRuns } from "cron-human" and get a clean function API without pulling in a framework.

CLI, library, and MCP share the same core. Whatever the CLI can do, the library can do, and the MCP server can do. The three surfaces are wrappers over the same parsing and scheduling logic. Adding a feature once gives you the same feature everywhere.

Node 20+. I chose to target modern Node rather than polyfill back to ancient versions. This keeps the codebase clean and lets me use things like the built-in Intl.DateTimeFormat for timezone handling without compromise.

MIT. Because open source tools that ask too much of their users don't get used.

What is cron-human trying to become?

This is the part of the post that matters most to me, so I'll be direct about it.

The small goal is that cron-human replaces three tabs and two mental context-switches with one terminal command. That's the immediate job of the package and I think it already does it well.

The medium goal is to be the canonical interface between cron and AI agents. As more scheduling decisions move into natural-language flows (Claude setting up cron jobs, Copilot editing CI schedules, custom agents orchestrating background tasks), I want the deterministic layer underneath those decisions to be a library that was designed for that usage pattern from day one. Most cron libraries were written for humans running bash scripts. cron-human is being written with the assumption that its caller is just as likely to be a model as a person.

The long goal, and this is where it gets more speculative, is to treat cron as a first-class piece of developer UX worth investing in. Cron is everywhere: every Kubernetes cluster, every CI pipeline, every indie SaaS backend, every hobbyist Raspberry Pi. The syntax has been around for fifty years and we have all just collectively agreed to live with its ergonomic limits. I don't think we have to. A small, focused tool that translates, validates, schedules, costs, and explains cron expressions, and that can be invoked by both humans and AI agents through the same interface, feels like a genuinely useful piece of infrastructure to have around.

That's what cron-human is trying to be. Some of it exists today. Some of it is roadmap. The 5,000-plus npm downloads so far tell me people are at least willing to try it, which is the only signal that actually matters at this stage.

Try it

npx cron-human "0 9 * * 1-5"

If you want the full CLI:

npm install -g cron-human

And if you want to wire it into an agent: cron-human --mcp starts the MCP server and you can point your client at it.

Source is on GitHub at AKforCodes/cron-human. Issues, PRs, and feature requests are all welcome. If you've got a cron use case that the current tool handles badly, tell me about it. That's usually where the best features come from.

Related

• Discourse X-Ray: Making Invisible Writing Structure Visible — another project built on the same pattern of wrapping LLMs in deterministic scaffolding.
• ScopeGuard: A Scope-Creep Radar for Client Projects — using LLMs only for the part they're good at, and doing everything else in boring code.