/schedule

Schedule recurring vault maintenance tasks using macOS launchd (or cron on Linux).

Usage

/schedule list                          # List scheduled jobs
/schedule add <job> <schedule>          # Add a scheduled job
/schedule remove <job>                  # Remove a scheduled job
/schedule run <job>                     # Run job immediately
/schedule status                        # Show job status and last run times

Examples

/schedule list
/schedule add health-check daily
/schedule add graph-rebuild hourly
/schedule add validate weekly
/schedule remove health-check
/schedule status

Available Jobs

Job	Description	Default Schedule
health-check	Run vault health check (scripts/health-check.js)	Daily at 6am
validate	Run frontmatter/link validation (scripts/validate.js)	Weekly on Monday
graph-rebuild	Rebuild knowledge graph index (scripts/generate-graph-enhanced.js)	Hourly
vault-index	Rebuild SQLite FTS5 search index (scripts/vault-to-sqlite.js)	Daily at 5am
backup	Git commit and push vault changes	Daily at midnight
weblink-check	Check for dead weblinks	Weekly on Sunday
custom	User-defined command	As specified

Schedule Formats

Format	Description	Example
hourly	Every hour at :00	hourly
daily	Every day at 6:00 AM	daily
daily@HH:MM	Every day at specific time	daily@09:30
weekly	Every Monday at 6:00 AM	weekly
weekly@DAY	Specific day at 6:00 AM	weekly@friday
cron EXPR	Cron expression (5 fields)	cron 0 */4 * * *

Instructions

1. Parse Command

Identify the subcommand:

• list - Show all scheduled jobs
• add - Create new scheduled job
• remove - Delete scheduled job
• run - Execute job immediately
• status - Show job status

2. Handle Subcommands

For list:

Read launchd plist files from ~/Library/LaunchAgents/:

ls -la ~/Library/LaunchAgents/com.vault.* 2>/dev/null

Display in table format:

Scheduled Vault Jobs
====================

| Job           | Schedule      | Status  | Last Run   |
|---------------|---------------|---------|------------|
| health-check  | Daily @ 06:00 | Active  | 2026-01-26 |
| graph-rebuild | Hourly        | Active  | 2026-01-26 |
| validate      | Weekly Mon    | Paused  | 2026-01-20 |

For add:

1. Parse job name and schedule
2. Generate launchd plist file
3. Write to ~/Library/LaunchAgents/com.vault.{{job}}.plist
4. Load the job: launchctl load ~/Library/LaunchAgents/com.vault.{{job}}.plist

Plist Template:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.vault.{{job}}</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>{{vault_path}}/scripts/{{script}}.js</string>
    </array>
    <key>WorkingDirectory</key>
    <string>{{vault_path}}</string>
    <key>StartCalendarInterval</key>
    {{schedule_dict}}
    <key>StandardOutPath</key>
    <string>{{vault_path}}/.claude/logs/{{job}}.log</string>
    <key>StandardErrorPath</key>
    <string>{{vault_path}}/.claude/logs/{{job}}.error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Schedule Dict Examples:

<!-- Daily at 6am -->
<dict>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>0</integer>
</dict>

<!-- Hourly -->
<dict>
    <key>Minute</key>
    <integer>0</integer>
</dict>

<!-- Weekly on Monday -->
<dict>
    <key>Weekday</key>
    <integer>1</integer>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>0</integer>
</dict>

For remove:

1. Unload the job: launchctl unload ~/Library/LaunchAgents/com.vault.{{job}}.plist
2. Delete the plist file
3. Confirm removal

For run:

Execute the job immediately:

launchctl start com.vault.{{job}}

Or run directly:

node scripts/{{script}}.js

For status:

Show status for all jobs:

launchctl list | grep com.vault

Display last run times from log files.

3. Job Definitions

Map job names to scripts:

const JOBS = {
  "health-check": {
    script: "health-check.js",
    defaultSchedule: "daily",
    description: "Run vault health check",
  },
  validate: {
    script: "validate.js",
    defaultSchedule: "weekly",
    description: "Validate frontmatter and links",
  },
  "graph-rebuild": {
    script: "generate-graph-enhanced.js",
    defaultSchedule: "hourly",
    description: "Rebuild knowledge graph index",
  },
  "vault-index": {
    script: "vault-to-sqlite.js",
    defaultSchedule: "daily@05:00",
    description: "Rebuild SQLite FTS5 search index",
  },
  backup: {
    script: "backup.sh",
    defaultSchedule: "daily@00:00",
    description: "Git commit and push",
  },
  "weblink-check": {
    script: "check-weblinks.js",
    defaultSchedule: "weekly@sunday",
    description: "Check for dead weblinks",
  },
};

4. Create Supporting Files

Ensure log directory exists:

mkdir -p .claude/logs

Create backup script if not exists (.claude/scripts/backup.sh):

#!/bin/bash
cd "$(dirname "$0")/../.."
git add -A
git commit -m "Automated backup: $(date +%Y-%m-%d)"
git push origin main

5. Linux Support (Alternative)

For Linux systems, use crontab instead:

# Add to crontab
(crontab -l 2>/dev/null; echo "0 6 * * * cd {{vault_path}} && node scripts/health-check.js") | crontab -

# List crontab
crontab -l | grep vault

# Remove from crontab
crontab -l | grep -v "{{job}}" | crontab -

6. Output Results

After any operation, display:

Schedule Operation Complete
===========================

Action: {{action}}
Job: {{job}}
Status: {{success/failed}}

{{details}}

Next run: {{next_scheduled_time}}
Log file: .claude/logs/{{job}}.log

Error Handling

• If launchctl fails, suggest running with admin privileges
• If plist syntax is invalid, show validation error
• If script doesn't exist, offer to create it
• If job already exists (for add), ask to overwrite

Related Skills

• [[.claude/skills/vault-maintenance/SKILL.md|/vault-maintenance]] - Manual maintenance
• [[.claude/skills/quality-report/SKILL.md|/quality-report]] - Quality metrics
• [[.claude/skills/check-weblinks/SKILL.md|/check-weblinks]] - Weblink validation