Skip to main content
Glama
Sign In
claude-cron

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community 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.
      3 npm
      MIT

    Appeared in Searches