Skip to main content
Glama
frr149

claude-cron

by frr149
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Claude Cron

License: MIT Bun TypeScript

Deferred tasks for AI coding assistants. MCP server + daemon that allows any AI coding assistant to schedule tasks for the future.

How does this compare to /loop? Claude Code 2.1.71 added /loop for in-session recurring tasks. It's great for ephemeral monitoring but dies when you close the terminal. claude-cron runs as an OS daemon — your tasks survive reboots and execute while you sleep. Read the full comparison.

Quickstart

bun install
bun test          # 38 tests
bun run typecheck # tsc --noEmit

Related MCP server: Claude Runner MCP

Claude Code Configuration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "claude-cron": {
      "command": "bun",
      "args": ["run", "/Users/fernando/code/claude-cron/src/index.ts"],
      "env": {
        "CLAUDE_CRON_DB": "/Users/fernando/.claude/claude-cron.sqlite",
        "GMAIL_ADDRESS": "frr@keepcoding.io",
        "GMAIL_APP_PASSWORD": "op://FRR DEV/...",
        "NTFY_TOPIC": "claude-cron-frr-xxx",
        "NTFY_URL": "https://ntfy.sh"
      }
    }
  }
}

Architecture

AI Assistant (Claude Code / Codex / Copilot)
    │ stdio (MCP protocol)
    ▼
MCP Server (src/index.ts)          ← Task CRUD
    │ SQLite (WAL mode)
    ▼
Runner / Daemon (src/runner.ts)    ← Loop: executes due tasks
    ├─ reminder  → notification + email + push
    ├─ shell     → Bun.spawn(command)
    ├─ claude    → claude -p --output-format text "prompt"
    ├─ codex     → codex --quiet "prompt"
    └─ copilot   → gh copilot suggest "prompt"

MCP Tools

Tool

Description

schedule_task

Schedule a task for the future

list_tasks

List tasks (filter by status, upcoming, tags)

cancel_task

Cancel a task by ID

run_now

Mark a task for immediate execution

install_daemon

Register the runner as an OS service

schedule_task

{
  name: "Nightly tests",
  type: "shell",              // reminder | shell | claude | codex | copilot
  when: "daily at 3:00",      // see "When expressions" below
  payload: {
    command: "cd ~/code/bfclaude && make test",  // shell
    // message: "...",         // reminder
    // prompt: "...",          // claude/codex/copilot
    // model: "haiku",
    // workingDir: "/path",
    // maxBudgetUsd: 0.10,
  },
  notify: ["notification", "email", "push"],
  notifyTo: "frr@keepcoding.io",
  tags: ["ci"],
}

when Expressions

Type

Examples

Natural language

"tomorrow 9:00", "in 30 minutes", "next friday at 3pm"

Cron (5 fields)

"0 9 * * 1", "*/5 * * * *"

ISO 8601

"2026-03-01T09:00:00Z", "2026-03-01"

Shortcuts

"every monday at 8", "daily at 9:00", "every 5 minutes"

Parsing: chrono-node (natural) + croner (cron) + regex (shortcuts). Shortcuts are evaluated before chrono-node so that "every monday at 8" is not interpreted as a single date.

Structure

src/
├── index.ts              # MCP server entry point (5 tools)
├── runner.ts             # Daemon: oneshot (launchd) or --loop (dev)
├── queue.ts              # SQLite: schema, CRUD, getDueTasks
├── scheduler.ts          # parseWhen(): chrono-node + croner + shortcuts
├── adapters/
│   ├── types.ts          # AIAdapter interface
│   ├── claude.ts         # claude -p --output-format text
│   ├── codex.ts          # codex --quiet (stub)
│   └── copilot.ts        # gh copilot suggest (stub)
├── notify/
│   ├── types.ts          # NotificationAdapter interface
│   ├── desktop.ts        # node-notifier (cross-platform)
│   ├── email.ts          # Direct SMTP to Gmail (TLS 465)
│   └── push.ts           # ntfy.sh (mobile + Apple Watch)
└── daemon/
    ├── types.ts          # DaemonInstaller interface
    ├── detect.ts         # process.platform → installer
    ├── launchd.ts        # macOS: ~/Library/LaunchAgents/
    ├── systemd.ts        # Linux: ~/.config/systemd/user/
    └── schtasks.ts       # Windows: Task Scheduler

Runner

Two modes:

# Oneshot (for launchd StartInterval / systemd timer)
bun run src/runner.ts

# Continuous loop (for dev or KeepAlive)
bun run src/runner.ts --loop

The daemon reads SQLite every 60s (configurable via CLAUDE_CRON_INTERVAL), executes due tasks, and sends notifications.

Cron tasks are automatically rescheduled after completion (next_run recalculated). One-off tasks transition to completed or failed.

Daemon

# Install (from Claude Code via MCP tool install_daemon, or manually):
# macOS:
bun run src/daemon/launchd.ts  # generates plist + launchctl load

# Verify
launchctl list | grep claude-cron
tail -f ~/Library/Logs/claude-cron.log

# Uninstall
launchctl unload ~/Library/LaunchAgents/com.claude-cron.runner.plist

Notifications

Channel

Requirements

Env vars

Desktop

node-notifier (included)

—

Email

Gmail App Password

GMAIL_ADDRESS, GMAIL_APP_PASSWORD

Push (ntfy)

ntfy app on mobile/watch

NTFY_TOPIC, NTFY_URL (opt), NTFY_TOKEN (opt)

SQLite Schema

tasks (
  id TEXT PRIMARY KEY,          -- nanoid 12 chars
  name, type, status,           -- type: reminder|shell|claude|codex|copilot
  run_at INTEGER,               -- Unix ts (one-off)
  cron TEXT,                    -- Cron expression (recurring)
  payload TEXT,                 -- JSON per type
  notify_via TEXT,              -- JSON array: ["notification","email","push"]
  notify_to TEXT,               -- Destination email
  next_run, last_run,           -- Timestamps
  run_count, last_result,       -- Executions + JSON result
  created_at, created_by, tags  -- Metadata
)

Dependencies

  • @modelcontextprotocol/sdk — MCP protocol

  • chrono-node — Natural language → Date

  • croner — Cron parsing + next run

  • nanoid — Short IDs

  • node-notifier — Cross-platform desktop notifications

  • zod — MCP input validation

  • bun:sqlite — built-in, zero deps

TODO

  • Configure MCP in real settings.json and test end-to-end

  • Install daemon with install_daemon and verify full cycle

  • Set up ntfy for push to mobile/watch

  • npm publish (name TBD)

  • CI with tests on macOS + Linux

  • README with real usage GIFs

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Scheduler

    RadiumGu
    A
    license
    Not graded
    quality
    D
    maintenance
    A robust task scheduler server built with Model Context Protocol for scheduling and managing various types of automated tasks including shell commands, API calls, AI tasks, and reminders.
    4
    MIT

  • Claude Runner MCP

    floriansmeyers
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for scheduling and executing Claude Code CLI tasks via cron expressions, featuring a web dashboard and webhook support. It enables users to dynamically create custom MCP servers, manage recurring AI jobs, and track execution history with token and cost analytics.
    24
    MIT

  • AgentCron

    Noriget
    A
    license
    Not graded
    quality
    D
    maintenance
    A hosted remote MCP server that lets your AI agent schedule tasks for later — reminders, delayed webhook callbacks, and recurring jobs. Read-only by design.
    1 npm
    MIT

Appeared in Searches