feat(dreamer): scheduled task automation system

[ojowwalker77]

Summary

• Add Matrix Dreamer - schedule and manage automated Claude tasks
• Uses native OS schedulers: launchd (macOS), crontab (Linux)
• Supports cron expressions + natural language scheduling (every day at 9am)
• Optional git worktree isolation for task execution

Key Features

Action	Description
add	Create a new scheduled task
list	Show all scheduled tasks
run	Manually trigger a task
remove	Delete a scheduled task
status	Check scheduler health
logs	View task output logs
history	View execution records

Changes

• 28 files changed, +3036 lines
• New matrix_dreamer MCP tool with 7 actions
• Database v5 migration: dreamer_tasks + dreamer_executions tables
• New dependencies: croner, cronstrue

Security

• All user inputs shell-escaped via shellEscape() (single-quote wrapping)
• XML escaping for launchd plist generation
• Parameterized SQL queries throughout

Test plan

• Verify matrix_dreamer({ action: 'add', name: 'test', schedule: 'every day at 9am', command: 'echo hello' }) creates task
• Verify launchctl list | grep dreamer shows registered task on macOS
• Verify matrix_dreamer({ action: 'list' }) returns created task
• Verify matrix_dreamer({ action: 'run', taskId: '...' }) executes task
• Verify matrix_dreamer({ action: 'remove', taskId: '...' }) removes task

[github-actions]

Version files synced to 2.1.0 from CHANGELOG.md

[greptile-apps]

Greptile Summary

Adds Matrix Dreamer, a scheduled task automation system that executes Claude commands using native OS schedulers (launchd for macOS, crontab for Linux). Tasks can be scheduled using cron expressions or natural language (e.g., "every day at 9am") and optionally run in isolated git worktrees.

Key Changes:

• 7 new actions: add, list, run, remove, status, logs, history
• Database migration v4→v5 adding dreamer_tasks and dreamer_executions tables
• Platform-specific schedulers with comprehensive security measures
• Natural language schedule parsing via croner and cronstrue libraries
• Optional git worktree isolation for task execution with automatic branch creation and push

Security Implementation:

• All user inputs shell-escaped using single-quote wrapping (shellEscape())
• XML escaping for launchd plist generation (escapeXml())
• Parameterized SQL queries throughout database layer
• LIKE pattern escaping in tag filtering (line 103-104 in store.ts)
• Temp file approach for crontab updates (fixes injection concern in linux.ts:186-194)

Architecture Highlights:

• Transactional task creation with automatic rollback on scheduler failure
• Execution tracking with status, duration, and error logging
• Platform abstraction via factory pattern
• Comprehensive input validation using TypeBox schemas

Confidence Score: 5/5

• Safe to merge - comprehensive security measures implemented throughout
• All identified security concerns have been properly addressed with multiple layers of protection: shell escaping via single-quote wrapping, XML escaping for plist files, parameterized SQL queries, and temp file usage for crontab updates. The code demonstrates defensive programming with proper error handling, transactional rollback, and validation at all entry points.
• No files require special attention

Important Files Changed

Filename	Overview
src/dreamer/scheduler/shell.ts	Implements secure shell escaping utilities using single-quote wrapping to prevent command injection
src/dreamer/scheduler/linux.ts	Linux crontab scheduler implementation with proper shell escaping and temp file approach for crontab updates
src/dreamer/scheduler/darwin.ts	macOS launchd scheduler with XML escaping for plist generation and shell escaping for command execution
src/dreamer/scheduler/base.ts	Base scheduler providing secure worktree script generation with comprehensive shell escaping
src/dreamer/actions/add.ts	Task creation with cron/natural language parsing and transactional rollback on scheduler failure
src/dreamer/store.ts	Database operations with parameterized queries and proper SQL escaping for LIKE patterns
src/db/migrate.ts	Database migration from v4 to v5 adding dreamer_tasks and dreamer_executions tables

Sequence Diagram

sequenceDiagram
    participant User
    participant MCP as MCP Tool Handler
    participant Add as Add Action
    participant Parser as Cron Parser
    participant Store as Database Store
    participant Factory as Scheduler Factory
    participant Scheduler as Platform Scheduler
    participant OS as OS Scheduler (launchd/crontab)

    User->>MCP: matrix_dreamer({ action: 'add', name: 'task', schedule: 'every day at 9am', command: 'echo hello' })
    MCP->>Add: handleAdd(input)
    
    Add->>Parser: parseSchedule('every day at 9am')
    Parser->>Parser: naturalLanguageToCron()
    Parser-->>Add: { expression: '0 9 * * *' }
    
    Add->>Store: createTask(task)
    Store->>Store: Parameterized SQL INSERT
    Store-->>Add: savedTask
    
    Add->>Factory: getScheduler()
    Factory->>Factory: Detect platform (darwin/linux)
    Factory-->>Add: scheduler instance
    
    Add->>Scheduler: register(task)
    
    alt Linux (crontab)
        Scheduler->>Scheduler: shellEscape() for all inputs
        Scheduler->>Scheduler: Write temp file with crontab content
        Scheduler->>OS: crontab /path/to/temp
        OS-->>Scheduler: Success
    else macOS (launchd)
        Scheduler->>Scheduler: escapeXml() + shellEscape()
        Scheduler->>Scheduler: Generate plist file
        Scheduler->>OS: launchctl load plist
        OS-->>Scheduler: Success
    end
    
    Scheduler-->>Add: Registration complete
    
    alt Registration fails
        Add->>Store: deleteTask(taskId)
        Store-->>Add: Rollback complete
        Add-->>User: Error: scheduler registration failed
    else Registration succeeds
        Add-->>User: Success with task details
    end
    
    Note over OS: At scheduled time (9am daily)
    OS->>OS: Execute: cd 'workDir' && claude -p 'command'
    OS->>OS: Log output to ~/.claude/matrix/dreamer/logs/

Loading

[greptile-apps]

_{27 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[github-actions]

Version files synced to 2.1.0 from CHANGELOG.md

[ojowwalker77]

@greptileai reassess