Scheduler

The Scheduler automates recurring tasks inside Mosaic. Set up cron jobs, file watchers, or interval timers that execute shell commands or Claude CLI prompts -- with run history, timeout enforcement, webhook notifications, and git auto-commit on completion.

Opening the Scheduler

Toggle the Scheduler panel with Ctrl+J. It appears in the sidebar dock alongside other panels.

Trigger Types

Each scheduled task uses one of three trigger types that determine when the task runs.

Cron

Standard five-field cron expressions: minute hour day-of-month month day-of-week.

Cron triggers are best for tasks that need to run at specific times or on a calendar-based schedule.

Interval

Run a task every N seconds. Simpler than cron when you just need "every X minutes."

Interval triggers start counting from when the task is enabled or the app starts.

File Watch

Trigger when files matching a glob pattern are created, modified, or deleted.

File watch triggers use debouncing to avoid firing repeatedly during rapid saves (e.g., when a formatter runs across many files).

Tip: File watch triggers are the foundation for "auto-run on save" workflows. Watch your source files and run the test suite, linter, or formatter automatically whenever you save. No more forgetting to run tests.

Action Types

Each task executes one of two action types when triggered.

Shell Command

Run any shell command. The command executes in the workspace's default working directory and supports full shell syntax including pipes, redirects, and chained commands.

Examples:

npm run test
npm run build && npm run lint
git status | head -20
./scripts/deploy.sh --env staging

Claude CLI Prompt

Send a prompt to the Claude Code CLI. Mosaic spawns a Claude session, passes your prompt, waits for completion, and records the output.

Examples:

Summarize yesterday's git commits and note any breaking changes
Review the files changed in the last hour for potential bugs
Generate API documentation for src/api/

Claude CLI prompts turn the scheduler into an autonomous code review and maintenance system. The agent runs on your schedule, examines your code, and produces reports or makes changes.

Tip: Combine cron triggers with Claude prompts for powerful automated workflows. Schedule a nightly prompt that reviews the day's changes for code quality issues, or a weekday morning prompt that summarizes what happened overnight.

Run History and Timeline

Every task execution is recorded with full details:

Timeline View

The timeline view provides a visual representation of scheduled and completed runs on a horizontal timeline. This makes it easy to:

• Spot patterns (does the linter always fail at 2 AM?)
• Identify failures at a glance
• See how long runs typically take
• Verify that scheduled runs are actually firing

Timeout Enforcement

Set a maximum execution time per task. If a task exceeds its timeout:

1. The process is terminated (the shell command or Claude session)
2. The run is recorded as timed out
3. Webhook notifications fire with the timeout status

This prevents runaway scripts from consuming resources indefinitely. A deploy script that normally takes 2 minutes but hangs for 30 minutes gets caught and stopped.

Tip: Set timeouts generously at first (2-3x the expected run time), then tighten them once you have baseline timing data from the run history.

Webhook Notifications

Each task can send notifications when it completes, through one or more webhook providers:

What Gets Sent

Webhook notifications include:

• Task name and description
• Status -- succeeded, failed, or timed out
• Duration -- how long the run took
• Output excerpt -- first/last lines of output (for Discord embeds)
• Error details -- error content on failure

Configure webhook URLs per task in the task settings. You can enable notifications for all runs, or only for failures.

Tip: Use ntfy for phone push notifications when monitoring critical scheduled tasks. A failed nightly backup or a broken test suite sends a notification directly to your phone, so you know about it before you start working the next morning.

Git Auto-Commit

Enable automatic git commits after successful task completion. When a scheduled task finishes and there are uncommitted changes in the working directory:

1. Mosaic stages the changed files
2. Creates a commit with a descriptive message referencing the task name
3. The commit appears in your git history with clear provenance

This is useful for tasks that generate or modify files:

Tip: Combine git auto-commit with webhook notifications: the task runs, commits changes, and notifies you that the commit was made. You can review it at your convenience.

Enable and Disable

Toggle individual tasks on or off without deleting them. Disabled tasks:

• Retain their full configuration (trigger, action, timeout, webhooks)
• Keep their run history intact
• Do not fire their triggers
• Can be re-enabled at any time

This is useful for temporarily pausing a task during development, debugging, or when you need to reduce system load.

Example Use Cases

Here are practical scenarios for each trigger type:

File Watch Examples

Cron Examples

Interval Examples

Keyboard Reference

Related

• Agent Orchestration -- agents managing scheduled tasks programmatically
• Project Board -- task management that can trigger scheduled actions
• Sidebar System -- docking and arranging the scheduler panel
• Daily Notes -- track what scheduled tasks accomplished today