codegeass 0.1.3

Claude Code Scheduler Framework - Orchestrate automated Claude Code sessions

CodeGeass

Claude Code Scheduler Framework - Orchestrate automated Claude Code sessions with templates, prompts and skills, executed via CRON with your Pro/Max subscription.

Features

• Scheduled Tasks: Define tasks with CRON expressions for automated execution
• Multi-Project Support: Manage multiple projects from a single installation with shared skills
• Skills Integration: Use Claude Code skills (.claude/skills/) for consistent, reusable prompts
• Multiple Strategies: Headless, autonomous, or skill-based execution
• Session Management: Track execution history with detailed logs
• CLI Interface: Full-featured command line tool for task management
• Web Dashboard: React + FastAPI dashboard for monitoring and management
• Notifications: Telegram and Discord notifications with plan approval support
• 24/7 Service: Systemd service for automatic scheduling

Installation

One-Line Install (Recommended)

Installs CodeGeass + 24/7 scheduler service (works on macOS and Linux):

curl -fsSL https://raw.githubusercontent.com/DonTizi/CodeGeass/main/install.sh | bash

This will:

• Install CodeGeass from PyPI
• Check/install Claude CLI
• Set up automatic scheduler (launchd on macOS, systemd on Linux)
• Configure directories

Manual Install

# From PyPI
pip install codegeass

# With notification support
pip install codegeass[notifications]

# Verify
codegeass --version

From Source

git clone https://github.com/DonTizi/CodeGeass.git
cd CodeGeass
pip install -e .

Uninstall

curl -fsSL https://raw.githubusercontent.com/DonTizi/CodeGeass/main/uninstall.sh | bash

Quick Start

1. Initialize Project

codegeass init

2. Create a Task

# Using a skill
codegeass task create \
  --name daily-review \
  --skill code-review \
  --schedule "0 9 * * 1-5" \
  --working-dir /path/to/project

# Using a direct prompt
codegeass task create \
  --name check-tests \
  --prompt "Run the test suite and report any failures" \
  --schedule "0 3 * * *" \
  --working-dir /path/to/project

3. List Tasks

codegeass task list

4. Run Task Manually

codegeass task run daily-review

5. Install CRON

codegeass scheduler install-cron

CLI Commands

Tasks

codegeass task list              # List all tasks
codegeass task show <name>       # Show task details
codegeass task create [opts]     # Create new task
codegeass task run <name>        # Run task manually
codegeass task enable <name>     # Enable task
codegeass task disable <name>    # Disable task
codegeass task delete <name>     # Delete task

Skills

codegeass skill list             # List available skills
codegeass skill show <name>      # Show skill details
codegeass skill validate <name>  # Validate skill format
codegeass skill render <name>    # Preview rendered skill

Scheduler

codegeass scheduler status       # Show scheduler status
codegeass scheduler run          # Run due tasks
codegeass scheduler run --force  # Run all enabled tasks
codegeass scheduler upcoming     # Show upcoming tasks
codegeass scheduler install-cron # Install crontab entry

Logs

codegeass logs list              # List recent logs
codegeass logs show <task>       # Show logs for task
codegeass logs tail <task>       # Tail recent logs
codegeass logs stats             # Show statistics

Projects

codegeass project list           # List registered projects
codegeass project add <path>     # Register a project
codegeass project show <name>    # Show project details
codegeass project set-default <name>  # Set default project
codegeass project init [path]    # Initialize project structure
codegeass project remove <name>  # Unregister a project
codegeass project enable <name>  # Enable a project
codegeass project disable <name> # Disable a project
codegeass project update <name>  # Update project settings

Notifications

codegeass notification list              # List notification channels
codegeass notification add               # Add a channel (interactive)
codegeass notification show <id>         # Show channel details
codegeass notification test <id>         # Test a channel
codegeass notification remove <id>       # Remove a channel
codegeass notification enable <id>       # Enable a channel
codegeass notification disable <id>      # Disable a channel
codegeass notification providers         # List available providers

Notifications

Send notifications to chat platforms (Telegram, Discord) when tasks start, complete, or fail.

Setup

1. Add a notification channel:

# Add Telegram channel (interactive prompts for bot token and chat ID)
codegeass notification add --provider telegram --name "My Alerts"

# Add Discord channel (interactive prompt for webhook URL)
codegeass notification add --provider discord --name "DevOps Channel"

2. Test the channel:

codegeass notification test <channel-id>

3. Create tasks with notifications:

codegeass task create \
  --name daily-backup \
  --prompt "Run backup script" \
  --schedule "0 2 * * *" \
  --notify <channel-id> \
  --notify-on start \
  --notify-on complete \
  --notify-on failure

Supported Providers

Provider	Requirements	Features
Telegram	Bot token from @BotFather, Chat ID	Message editing, HTML formatting
Discord	Webhook URL	Markdown formatting

Configuration

Channels are stored in config/notifications.yaml (non-sensitive config). Credentials are stored in ~/.codegeass/credentials.yaml (secrets, not in repo).

Message Editing

For Telegram, notifications are edited in-place rather than sending multiple messages:

• Task start: Shows "Running..."
• Task complete: Updates same message with result and duration

Skills

Skills are Claude Code prompt templates stored in .claude/skills/. They follow the Agent Skills open standard.

Included Skills

• review: Comprehensive code review for PRs or recent changes (correctness, security, performance, maintainability, tests)
• security-scan: Deep security analysis with secrets detection, dependency vulnerabilities, and CWE references
• code-review: Automated code review with security, performance, and maintainability focus
• security-audit: Deep security analysis for OWASP vulnerabilities and secrets
• test-runner: Execute and analyze test suites
• dependency-check: Analyze dependencies for updates and vulnerabilities

Shared Skills

Place skills in ~/.codegeass/skills/ to make them available across all registered projects. Project-specific skills in .claude/skills/ take priority over shared skills with the same name.

Skill Format

---
name: my-skill
description: What the skill does
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

# Skill Instructions

Instructions for $ARGUMENTS.

## Dynamic Context
- Status: !`git status`

Configuration

config/schedules.yaml

tasks:
  - name: daily-code-review
    skill: code-review
    schedule: "0 9 * * 1-5"
    working_dir: /home/user/projects/myapp

  - name: weekly-security-audit
    skill: security-audit
    schedule: "0 2 * * 0"
    working_dir: /home/user/projects/myapp
    autonomous: true

config/settings.yaml

claude:
  default_model: sonnet
  default_timeout: 300
  unset_api_key: true

scheduler:
  check_interval: 60
  max_concurrent: 1

Subscription Usage

Important: CodeGeass is designed to use your Claude Pro/Max subscription, NOT API credits.

The CRON runner script (scripts/cron-runner.sh) automatically unsets ANTHROPIC_API_KEY to ensure your subscription is used.

Architecture

codegeass/
├── src/codegeass/
│   ├── core/           # Domain entities and value objects
│   ├── storage/        # Persistence layer (YAML, JSON)
│   │   └── project_repository.py  # Multi-project registry
│   ├── factory/        # Task and skill registries
│   │   └── skill_resolver.py  # Project + shared skills with priority
│   ├── execution/      # Claude Code execution strategies
│   ├── scheduling/     # CRON parsing and job scheduling
│   ├── notifications/  # Chat notifications (Telegram, Discord)
│   └── cli/            # Click CLI commands
├── dashboard/          # Web dashboard (React + FastAPI)
├── config/             # Configuration files
├── data/               # Runtime data (logs, sessions)
├── scripts/            # CRON runner script
└── .claude/skills/     # Claude Code skills

~/.codegeass/           # Global user configuration
├── projects.yaml       # Project registry
├── credentials.yaml    # Secrets
└── skills/             # Shared skills (all projects)

Web Dashboard

A React + FastAPI dashboard for managing tasks and viewing logs.

cd dashboard
./setup.sh    # First-time setup
./run.sh      # Run frontend (5173) + backend (8001)

Then open http://localhost:5173

Development

# Run tests
pytest tests/ -v

# Type checking
mypy src/codegeass

# Linting
ruff check src/codegeass

# Build package
python -m build

Documentation

• Live docs: https://dontizi.github.io/codegeass/
• Build locally: pip install -e ".[docs]" && mkdocs serve

Release Process

Releases are automated via GitHub Actions when a tag is pushed:

# Use the release skill
/release 0.2.0

# Or manually: update version, commit, tag, push

The workflow will:

1. Build and test the package
2. Publish to PyPI (via OIDC trusted publishing)
3. Create a GitHub release with assets
4. Deploy versioned documentation

License

MIT