About this project

# Claude Code Session Reset Scheduler ## Overview This is a GitHub Actions-based automation tool that manages Claude Code session resets on a scheduled basis. The system triggers automated session resets at strategically chosen times to align with typical work periods, ensuring users have a fresh 5-hour usage window when needed. ## Key Capabilities ### Automated Session Management - Triggers four daily session resets aligned with common work periods - Uses a 5-hour countdown system between trigger and reset events - Customizable schedule via cron expressions ### Health Monitoring - Built-in Q&A verification checks (e.g., "1+1=?") to confirm Claude Code functionality - Logs health check results with timestamps - Verifies system is operational before marking resets as complete ### Multi-Token Support - Configure primary and backup OAuth tokens for reliability - Track activity per token in logs - Redundancy if one token fails ### Activity Logging - Monthly CSV log files stored in `logs/YYYYMM-session-log.csv` - Records include timestamp, event type, token ID, and reset time - Automated Git commits preserve log history ### Timeout Protection - Job-level timeout: 5 minutes - Step-level timeout: 2 minutes per action - Prevents runaway executions from consuming resources ## Default Schedule (UTC+8) | Trigger Time | Reset Time | Coverage | |------------|-----------|----------| | 05:23 | 10:00 AM | Morning work period | | 10:23 | 3:00 PM | Afternoon work period | | 17:23 | 10:00 PM | Evening work period | | 22:23 | 3:00 AM (next day) | Late night coverage | Each trigger fires 5 hours before the desired reset time. The system uses `:23` minutes to avoid GitHub Actions execution congestion. ## Setup Instructions 1. **Generate OAuth Token**: Run `claude setup-token` and copy the generated token 2. **Add Secrets**: Configure `CLAUDE_CODE_OAUTH_TOKEN_1` and optionally `CLAUDE_CODE_OAUTH_TOKEN_2` in GitHub repository settings 3. **Enable Actions**: Ensure the repository has `id-token: write` permission for GitHub Actions 4. **Activate**: Push the workflow file to trigger the scheduler ## Customization Edit `.github/workflows/auto-checkin.yml` to modify cron schedules. The timing formula is: ``` Trigger Time + 5 hours = Session Reset Time ``` Examples: - Single daily reset at 9:00 AM: use cron `23 20 * * *` (4:23 AM UTC triggers reset at 9:00 AM UTC+8) - Twice daily at 10:00 AM and 4:00 PM: use cron `23 21,3 * * *` ## Testing - **GitHub Actions**: Navigate to the Actions tab and manually run the workflow - **Local Testing**: `uv run --python 3.13 python src/log_qa_check.py --token TOKEN_1` ## File Structure ``` .github/workflows/auto-checkin.yml # Scheduler configuration src/log_qa_check.py # Q&A and logging script logs/YYYYMM-session-log.csv # Monthly activity records ```n ## Troubleshooting - **OAuth errors**: Regenerate token with `claude setup-token` and verify secret names match exactly - **Workflow timeouts**: Ensure the latest version with timeout protections is deployed - **Wrong times**: Verify UTC conversions and remember GitHub Actions may have slight execution delays - **No logs**: Check Claude authentication status and test locally before relying on automation ## Security - Never hardcode tokens in source code - Use GitHub Secrets for all sensitive values - Rotate OAuth tokens periodically - Limit repository access to trusted contributors The project includes Architecture Decision Records (ADRs) documenting design choices around scheduling optimization, timeout configuration, and health check implementation.