claude-code-scheduler

claude-code-scheduler

A GUI application and CLI tool that provides scheduling and management for Claude Code CLI sessions with REST API control.

Features

• Scheduling: Manual, interval, calendar, and file-watch triggers
• Data Model: Job → Task → Run hierarchy for organized workflows
• REST API: External control via HTTP (port 5679)
• Profiles: Environment configurations for AWS Bedrock, Z.AI, Anthropic API
• CLI: Full management via command line with agent-friendly help
• Export/Import: Backup and share job configurations

Quick Start

# Install
git clone https://github.com/dnvriend/claude-code-scheduler.git
cd claude-code-scheduler
uv tool install .

# Launch GUI
claude-code-scheduler gui

# Check health
curl http://127.0.0.1:5679/api/health

Headless Server Mode

Run as a headless server without GUI for CI/CD, containers, or daemon use:

# Launch headless server
claude-code-scheduler server

# With options
claude-code-scheduler server --port 8080 --workers 5

# Verbose logging
claude-code-scheduler server -v

Option	Default	Description
--port, -p	5679	REST API port
--workers, -w	3	Max parallel jobs
-v	-	Verbose logging (-vv for debug)

The server provides the same REST API as the GUI and supports parallel job execution.

Data Model

Job (1) → Task (many) → Run (many)

• Job: Container for related tasks with working directory
• Task: A Claude Code prompt with profile and schedule
• Run: Execution record with status and output

CLI Commands

# Jobs
claude-code-scheduler cli jobs list              # List all jobs
claude-code-scheduler cli jobs create --name "Feature" --working-directory ~/projects/repo
claude-code-scheduler cli jobs run <job-id>      # Start sequential execution
claude-code-scheduler cli jobs export <job-id> -o backup.json
claude-code-scheduler cli jobs import -i backup.json

# Tasks (use --zai or --bedrock shortcuts)
claude-code-scheduler cli tasks create \
    --name "Code Review" \
    --prompt "Review code for issues" \
    --zai \
    --job <job-id>

claude-code-scheduler cli tasks list
claude-code-scheduler cli tasks run <task-id>

# Runs
claude-code-scheduler cli runs list
claude-code-scheduler cli runs stop <run-id>

# Profiles
claude-code-scheduler cli profiles list
claude-code-scheduler cli profiles get <profile-id>

Profile Shortcuts

Shortcut	Profile	Description
--zai	Z.AI API	Z.AI Claude API access
--bedrock	AWS Bedrock	AWS Bedrock Claude access

Debug Commands

# File-based inspection (no GUI required)
claude-code-scheduler debug all       # Complete state dump
claude-code-scheduler debug tasks     # List all tasks
claude-code-scheduler debug runs      # Recent runs
claude-code-scheduler debug settings  # Current settings

REST API

# Health check
curl http://127.0.0.1:5679/api/health

# List resources
curl http://127.0.0.1:5679/api/jobs
curl http://127.0.0.1:5679/api/tasks
curl http://127.0.0.1:5679/api/runs

# Create task
curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"Test","prompt":"echo hi","profile":"<profile-id>"}' \
  http://127.0.0.1:5679/api/tasks

# Run job
curl -X POST http://127.0.0.1:5679/api/jobs/{id}/run

Development

make install    # Install dependencies
make test       # Run tests
make lint       # Run linting
make typecheck  # Type checking
make pipeline   # Full CI pipeline

Data Files

~/.claude-scheduler/
├── jobs.json        # Job configurations
├── tasks.json       # Task configurations
├── runs.json        # Execution history
├── profiles.json    # Environment profiles
├── settings.json    # Application settings
└── logs/            # Per-run output logs

License

MIT License - see LICENSE

Author

Dennis Vriend - @dnvriend

---

Built with Claude Code