Claude Code Scheduler

A comprehensive Python web application for scheduling and executing Claude Code commands with advanced features including macOS sleep prevention, real-time monitoring, and comprehensive logging.

Features

Core Functionality

Prompt Management: Full CRUD operations for Claude command prompts
Advanced Scheduling: APScheduler integration with cron-like functionality
Sleep Prevention: Automatic macOS sleep prevention during scheduled executions
Real-time Monitoring: Live status updates and execution tracking
Comprehensive Logging: Detailed execution history with success/failure tracking

Web Interface

Modern UI: Responsive Bootstrap 5 interface with dark/light theme support
Dashboard: Overview of system status, upcoming executions, and recent activity
Calendar View: Visual scheduling interface for managing execution times
Bulk Operations: Schedule multiple prompts with customizable intervals
Real-time Updates: WebSocket-like updates for live status monitoring

Security & Safety

Input Validation: Comprehensive validation to prevent command injection
Resource Monitoring: System resource usage tracking with psutil
Execution Timeouts: Configurable timeout limits for command execution
Emergency Stop: Safe shutdown procedures with cleanup

Technology Stack

Backend: Flask 3.0 with SQLAlchemy ORM
Database: SQLite with WAL mode for concurrent access
Scheduling: APScheduler with SQLAlchemy job store
Frontend: Bootstrap 5 with responsive design
System Integration: macOS caffeinate integration for sleep prevention

Installation

Prerequisites

Python 3.8 or higher
macOS (for sleep prevention features)
Claude Code CLI installed and accessible in PATH

Setup

Clone the repository

git clone <repository-url>
cd claude-code-scheduler

Create virtual environment

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

Install dependencies
```
pip install -r requirements.txt
```
Initialize database
```
python run.py init-db
```
Start the application
```
python run.py
```
Access the web interface Open your browser to http://127.0.0.1:5000

Usage

Creating Prompts

Navigate to Prompts → New Prompt
Fill in the prompt details:
- Name: Descriptive name (auto-generated if empty)
- Description: Optional description
- Command: Claude command without "claude " prefix
- Working Directory: Optional execution directory
- Schedule: When to execute (optional)
- Status: Current status (pending/finished/etc.)

Scheduling Executions

Single Prompt: Set execution time in the prompt form
Bulk Scheduling: Use Scheduler → Bulk Schedule for multiple prompts
Calendar View: Visual scheduling interface at Scheduler → Calendar

Monitoring

Dashboard: Real-time overview of system status
Logs: Detailed execution history with filtering
Status Page: Comprehensive system health information
API Endpoints: RESTful API for programmatic access

Configuration

Environment Variables

# Database
DATABASE_URL=sqlite:///data/scheduler.db

# Security
SECRET_KEY=your-secret-key-here

# Execution
EXECUTION_TIMEOUT=3600        # Command timeout in seconds
MAX_LOG_SIZE=1048576         # Log file size limit
LOG_LEVEL=INFO               # Logging level

# UI
ITEMS_PER_PAGE=20            # Pagination size
THEME=light                  # Default theme

Application Settings

Access settings through Scheduler → Settings to configure:

Execution timeout limits
Log retention policies
UI preferences
Notification settings

API Reference

The application provides a RESTful API for programmatic access:

Endpoints

GET /api/status - Application status
GET /api/prompts - List prompts with pagination
GET /api/prompts/{id} - Get specific prompt details
POST /api/prompts/{id}/execute - Execute prompt immediately
POST /api/prompts/{id}/schedule - Schedule prompt execution
GET /api/jobs - List scheduled jobs
DELETE /api/jobs/{id} - Remove scheduled job
GET /api/execution-history - Execution history
GET /api/statistics - Application statistics

Example Usage

# Get application status
curl http://localhost:5000/api/status

# Execute a prompt immediately
curl -X POST http://localhost:5000/api/prompts/1/execute

# Schedule a prompt
curl -X POST http://localhost:5000/api/prompts/1/schedule \
  -H "Content-Type: application/json" \
  -d '{"execution_time": "2024-01-01T10:00:00"}'

Architecture

Directory Structure

claude-code-scheduler/
├── app/
│   ├── models.py              # Database models
│   ├── routes/                # Flask blueprints
│   │   ├── main.py           # Dashboard & main pages
│   │   ├── prompts.py        # Prompt CRUD operations
│   │   ├── scheduler.py      # Scheduling management
│   │   └── api.py            # REST API endpoints
│   ├── services/             # Business logic
│   │   ├── scheduler_service.py    # APScheduler integration
│   │   ├── execution_service.py    # Command execution
│   │   └── sleep_prevention.py    # macOS sleep management
│   ├── templates/            # Jinja2 templates
│   └── utils/                # Utilities and helpers
├── config/                   # Configuration files
├── data/                     # SQLite database
├── logs/                     # Application logs
└── run.py                    # Application entry point

Key Components

Scheduler Service: Manages APScheduler integration and job lifecycle
Execution Service: Handles Claude command execution with timeout and logging
Sleep Prevention: macOS caffeinate integration for uninterrupted execution
Web Interface: Flask routes with Bootstrap UI
API Layer: RESTful endpoints for programmatic access

Advanced Features

Sleep Prevention

The application automatically prevents macOS system sleep during scheduled executions using the caffeinate command. This ensures:

Displays don't sleep during execution
System doesn't enter idle sleep
Network connections remain active
Automatic cleanup when execution completes

Error Handling

Comprehensive error handling includes:

Command execution timeouts
Network connectivity issues
Database transaction failures
Scheduler service interruptions
Graceful degradation for non-critical failures

Performance Optimization

SQLite WAL mode for concurrent access
Background thread execution
Efficient database queries with indexing
Pagination for large datasets
Resource usage monitoring

Troubleshooting

Common Issues

Scheduler not starting
- Check database permissions
- Verify SQLite file is writable
- Review application logs
Commands not executing
- Verify Claude Code is in PATH
- Check working directory permissions
- Review execution logs
Sleep prevention not working
- Ensure running on macOS
- Verify caffeinate is available
- Check system permissions

Logging

Application logs are available in multiple locations:

Web Interface: /logs page
File System: logs/scheduler.log
Database: Execution history table

Debug Mode

Enable debug mode for development:

FLASK_ENV=development python run.py serve --debug

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section
Review application logs
Create an issue on GitHub
Include relevant log files and system information

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
app		app
config		config
.gitignore		.gitignore
README.md		README.md
prompts.md		prompts.md
requirements.txt		requirements.txt
run.py		run.py

guntarion/claude-code-scheduler

Folders and files

Latest commit

History

Repository files navigation