Claude Scheduler

macOS app · CLI · agent skill

A native menu bar app that runs headless Claude Code tasks on a schedule,
a command-line interface that scripts everything the app does,
and a skill that lets coding agents schedule tasks for you.

Define a task — prompt, model, schedule, allowed tools — and it runs claude -p on a launchd schedule, even when the app is closed. When a run finishes, hooks fire: post the result to Discord or Slack, run a shell command, or show a notification.

macOS only (14.0+). Built with SwiftUI and Swift 6; scheduling is delegated to launchd, so no daemon and no background app required.

Features

• Real scheduling — one LaunchAgent per task. Tasks fire on time whether or not the app is running; schedules missed during sleep fire once on wake.
• Two surfaces — a full control window (sidebar, configuration, hooks, run history) and a compact menu bar popover for glanceable status.
• Hooks — per-event automations (before launch, after launch, on done, on failure): shell commands, webhooks with {{VAR}} templating (Discord/Slack-ready, 429 retry), and macOS notifications.
• Run records — every run stores duration, exit code, token usage, cost, the full log, and the Claude session id, so any run can be resumed in the terminal with claude --resume <session-id>.
• Token tracking — per-run, weekly, and all-time token counters across all tasks.
• Safety limits — per-task timeouts (SIGTERM → SIGKILL), overlap guards so a slow run never stacks, capped log sizes, and explicit tool allowlists per task.
• Agent-friendly CLI — everything the app does is scriptable; see below.

How it works

Menu bar app ──writes──► ~/Library/LaunchAgents/<task>.plist ──► launchd
     ▲                                                              │
     └──── DistributedNotificationCenter (live status) ◄─── claude-scheduler-runner
                                                                    │
     ~/Library/Application Support/ClaudeScheduler/                 │
         tasks/<uuid>.json      task definitions                    │
         runs/<uuid>/*.json     run records                       ◄─┘
         logs/<uuid>/*.log      stream-json + hook output
         bin/…runner            stable symlink into the app bundle

The app writes task definitions as JSON and registers a LaunchAgent per task. A separate runner binary — invoked by launchd — spawns claude -p --output-format stream-json, tees output to the run log, parses the result event, enforces timeouts, and fires hooks. Disk is the single source of truth; distributed notifications keep a running app in sync.

Install

Homebrew

brew tap tornikegomareli/tap
brew install --cask claude-scheduler

The app installs to /Applications. Launch it once so the menu bar item and the CLI symlink are set up. To update or remove:

brew upgrade --cask claude-scheduler     # update to the latest release
brew uninstall --cask claude-scheduler   # remove the app
brew uninstall --zap claude-scheduler    # also remove tasks, logs, and settings

From source

git clone https://github.com/tornikegomareli/claude-scheduler.git
cd claude-scheduler
Scripts/compile_and_run.sh --test   # test + build + install to ~/Applications + launch

Or open ClaudeScheduler.xcodeproj and run. The project file is generated from project.yml with XcodeGen — regenerate after adding files.

Requires the Claude Code CLI. The runner locates it automatically (~/.local/bin → Homebrew → /usr/local/bin); the path can be overridden in Settings.

CLI

The runner doubles as a complete task-management CLI. A stable path always points at the installed binary:

alias claude-scheduler='"$HOME/Library/Application Support/ClaudeScheduler/bin/claude-scheduler-runner"'

# create a task — prints its UUID, registers the schedule immediately
claude-scheduler add --name "Daily digest" \
    --prompt-file ~/prompts/digest.md --schedule daily@09:00 \
    --tools WebSearch,WebFetch,Read,Write --model sonnet

claude-scheduler add --json - < task.json       # full JSON spec via stdin
claude-scheduler list [--json]                  # all tasks + last-run state
claude-scheduler show <task-uuid>               # one task's stored JSON
claude-scheduler enable|disable <task-uuid>     # pause / resume
claude-scheduler remove <task-uuid>             # delete task + agent + history
claude-scheduler kickstart <task-uuid>          # fire now via launchd
claude-scheduler help                           # full reference

Schedule grammar: manual · daily@09:00[,18:30…] · weekly@mon,fri@08:15 · every@30m|2h|900s.

Tasks created from the CLI appear in a running app instantly. Hook variables available to shell hooks (as environment) and webhook/notification templates (as {{VAR}}): TASK_NAME, RUN_STATE, EXIT_CODE, COST_USD, TOTAL_TOKENS, DATE, LOG_FILE, RESULT_TEXT_FILE, CLAUDE_SESSION_ID, and more.

Agent skill

The repository ships a skill that teaches coding agents to drive the CLI — so you can tell an agent "schedule this prompt to run every morning at 8" and it creates the task, verifies the schedule, and wires up hooks on its own. Install it deterministically:

mkdir -p ~/.claude/skills
cp -R skills/claude-scheduler ~/.claude/skills/

The skill covers the schedule grammar, hook JSON shapes, verification steps, and guardrails (confirming run frequency, never widening permissions unprompted).

Project layout

Notes

• launchd runs with a minimal PATH; the runner never relies on the inherited environment.
• The first headless run may show a keychain prompt for the Claude binary — do one watched "Run Now" after installing.
• Prompt files are re-read at every fire, so editing the file applies to the next run.
• Schedules missed while the Mac is powered off are skipped (standard launchd behavior).