🤖 Claude Code Session Reset Scheduler

Automated session management system that ensures fresh Claude Code quotas during your working hours

A GitHub Actions-powered scheduler that automatically triggers Claude Code session resets at optimal times, maintaining a 5-hour countdown to ensure new quotas are available when you need them most. Features health monitoring through simple Q&A checks.

✨ Key Features

• 🔄 Automatic Session Management - Triggers 4 daily resets aligned with work periods
• ⏰ Smart Timing - 5-hour countdown ensures sessions refresh during productive hours
• 🧪 Health Monitoring - Built-in Q&A checks verify system functionality
• 🔐 Multi-Token Support - Configure backup tokens for reliability
• 📊 Activity Logging - Track all resets in monthly CSV logs
• ⚡ Fast Failure Protection - 5-minute job timeout prevents resource waste

📅 Default Schedule (UTC+8 Timezone)

The system triggers session resets 5 hours before your target work periods:

🚀 Quick Start

Step 1: Get the Repository

Choose one option:

Option A: Fork (Recommended for personal use)

# 1. Fork this repo on GitHub
# 2. Clone your fork
git clone https://github.com/codeotter0201/claude-daily-check-in.git
cd claude-daily-check-in

Option B: Clone directly

git clone https://github.com/codeotter0201/claude-daily-check-in.git
cd claude-daily-check-in

Step 2: Generate OAuth Token

claude setup-token

Copy the generated oauth_token_... value.

Step 3: Add to GitHub Secrets

1. Navigate to: Settings → Secrets and variables → Actions
2. Create new secrets:

Step 4: Done!

✅ The scheduler is now active and will run automatically based on the default schedule.

• First trigger will happen at the next scheduled time
• Check the Actions tab in your GitHub repository to monitor runs
• No push needed unless you modify the schedule

⚙️ Customizing Schedule Times

Understanding the Timing System

Each trigger initiates a 5-hour countdown. The formula is:

Trigger Time + 5 hours = Session Reset Time

Quick Examples

schedule:
  - cron: "23 20 * * *" # Triggers at 4:23 AM → Resets at 9:00 AM

schedule:
  - cron: "23 21,3 * * *" # Triggers at 5:23 AM & 11:23 AM

schedule:
  - cron: "23 20,1,6 * * *" # Triggers 5 hours before each

How to Modify Schedule

1. Edit .github/workflows/auto-checkin.yml
2. Find the schedule line (~line 12):

   - cron: "23 21,2,9,14 * * *" # Current schedule
   

3. Calculate your times:
   • Choose reset times (in your timezone)
   • Subtract 5 hours for trigger times
   • Convert to UTC
   • Use :23 minutes (avoids congestion)
4. Push your changes to apply the new schedule:

   git add .github/workflows/auto-checkin.yml
   git commit -m "Update schedule times"
   git push origin main
   

🧪 Testing Your Setup

Via GitHub Actions (Recommended)

1. Go to Actions tab
2. Select "Claude Code Session Reset Scheduler"
3. Click "Run workflow"

Local Testing

# Test Q&A functionality
uv run --python 3.13 python src/log_qa_check.py --token TOKEN_1

# View logs
cat logs/$(date +%Y%m)-session-log.csv

📊 Session Logs

Monthly CSV files track all activities:

Location: logs/YYYYMM-session-log.csv

Format:

timestamp,event_type,token_id,reset_time_utc8
2025-09-04 05:24:27,SESSION-RESET-TRIGGER,TOKEN_1,2025-09-04 18:24:27

🛠️ Architecture

System Flow

graph LR
    A[GitHub Actions] -->|Scheduled Trigger| B[Claude Code]
    B -->|"Q&A Check: 1+1=?"| C[Health Verification]
    C -->|Log Event| D[CSV File]
    D -->|Git Commit| E[Repository]
    B -->|5-hour Countdown| F[Session Reset]

Project Structure

📁 claude-daily-check-in/
├── 📁 .github/workflows/
│   └── 📄 auto-checkin.yml         # Scheduler configuration
├── 📁 src/
│   └── 🐍 log_qa_check.py          # Q&A & logging script
├── 📁 logs/                        # Session records
│   └── 📊 YYYYMM-session-log.csv
├── 📄 README.md                    # This file
└── 📄 ADR-*.md                     # Architecture decisions

🔧 Advanced Configuration

Multiple Token Setup

Benefits of using multiple tokens:

• ✅ Redundancy - Backup if one fails
• ✅ Load Distribution - Parallel processing
• ✅ Tracking - Individual token monitoring

🐛 Troubleshooting

# Check Claude status
claude --version
claude auth status

# Test locally
claude -p "1+1=?"

# Manual trigger
uv run --python 3.13 python src/log_qa_check.py --token TOKEN_1

📈 Monitoring

Health Checks

• ✅ GitHub Actions - Review workflow runs
• ✅ CSV Logs - Verify monthly records
• ✅ Git History - Check automated commits
• ✅ Session Availability - Monitor actual resets

Maintenance Tasks

• 📅 Monthly - Review log files
• 🔄 Quarterly - Rotate OAuth tokens
• 📊 As Needed - Adjust schedule based on usage

🔒 Security

⚠️ Important Security Practices:

• Never hardcode tokens in code
• Use GitHub Secrets for sensitive data
• Rotate OAuth tokens regularly
• Limit repository access permissions

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📝 Version History

v2.3.0 (Current)

• ✅ Workflow timeout protection (5-minute job, 2-minute steps)
• ✅ Fast failure mechanism prevents 6-hour runaway executions
• ✅ Integrated Q&A health checks
• ✅ Enhanced logging with reset time calculations
• ✅ Local testing capabilities
• ✅ Optimized cron timing (:23 minutes)

📚 Documentation

• ADR-001: Session Reset Schedule
• ADR-002: Timing Optimization
• ADR-003: Q&A Health Checks
• ADR-004: Workflow Timeout Configuration
• Official Documentation
• Product Requirements