CC AutoRenew 🚀

Never miss a Claude Code renewal window again! Automatically maintains your 5-hour usage blocks with optional scheduled start times.

🎯 Problem

Claude Code operates on a 5-hour subscription model that renews from your first message. If you:

• Start coding at 5pm (block runs 5pm-10pm)
• Don't use Claude again until 11:01pm
• Your next block runs 11pm-4am (missing an hour!)

Session Burning Problem: Starting the daemon at random times can waste precious hours of your block. If you want to code from 9am-2pm but start the daemon at 6am, you've burned 3 hours!

Solution: CC AutoRenew prevents both gaps AND session burning:

• 🚫 Prevents Gaps - Automatically starts new sessions when blocks expire
• ⏰ Prevents Session Burning - Schedule when monitoring begins (--at "09:00")
• 🎯 Perfect Timing - Start your 5-hour block exactly when you need it

✨ Features

• 🔄 Automatic Renewal - Starts Claude sessions exactly when needed
• ⏰ Scheduled Start Times - Set when daemon begins monitoring (--at "09:00")
• 🛑 Scheduled Stop Times - Set when daemon stops monitoring (--stop "17:00")
• 🌅 Daily Auto-Restart - Automatically resumes next day at start time
• 📊 Smart Monitoring - Integrates with ccusage for accurate timing
• 🎯 Intelligent Scheduling - Checks more frequently as renewal approaches
• 📝 Detailed Logging - Track all renewal activities with WAITING/ACTIVE/STOPPED states
• 📊 Live Dashboard - Real-time monitoring with progress bars and renewal schedules
• 💬 Custom Messages - Use --message to send contextual renewal messages instead of generic greetings
• 🛡️ Failsafe Design - Multiple fallback mechanisms and prevents renewals near stop time
• 🖥️ Cross-platform - Works on macOS and Linux
• ⚡ Clock-only Mode - Use --disableccusage flag to bypass ccusage entirely

🚀 Quick Start

# Clone the repository
git clone https://github.com/aniketkarne/CCAutoRenew.git
cd CCAutoRenew

# Make scripts executable
chmod +x *.sh

# Interactive setup (recommended)
./setup-claude-cron.sh

# OR manual daemon start
./claude-daemon-manager.sh start
./claude-daemon-manager.sh start --at "09:00"  # with start time
./claude-daemon-manager.sh start --at "09:00" --stop "17:00"  # with start/stop times
./claude-daemon-manager.sh start --message "continue working on my project"  # with custom message
./claude-daemon-manager.sh start --at "09:00" --stop "17:00" --disableccusage  # clock-only mode

That's it! The daemon will now run in the background and automatically renew your Claude sessions.

📋 Prerequisites

• Claude CLI installed and authenticated
• Bash 4.0+ (pre-installed on macOS/Linux)
• (Optional) ccusage for precise timing

🔧 Installation

1. Install Claude CLI

First, ensure you have Claude Code installed:

# Follow the official installation guide
    # https://www.anthropic.com/claude-code

2. Install ccusage (Optional but Recommended)

For accurate renewal timing:

# Option 1: Global install
npm install -g ccusage

# Option 2: Use without installing
npx ccusage@latest
bunx ccusage

3. Setup CC AutoRenew

# Clone this repository
git clone https://github.com/aniketkarne/CCAutoRenew.git
cd cc-autorenew

# Make all scripts executable
chmod +x *.sh

# Test your setup
./test-claude-renewal.sh

📖 Usage

Managing the Daemon

# Start the auto-renewal daemon
./claude-daemon-manager.sh start

# Start with scheduled activation time
./claude-daemon-manager.sh start --at "09:00"
./claude-daemon-manager.sh start --at "2025-01-28 14:30"

# Start with both start and stop times
./claude-daemon-manager.sh start --at "09:00" --stop "17:00"
./claude-daemon-manager.sh start --at "2025-01-28 09:00" --stop "2025-01-28 17:00"

# Start with clock-only mode (bypass ccusage entirely)
./claude-daemon-manager.sh start --at "09:00" --stop "17:00" --disableccusage

# Start with custom renewal message (useful for context continuity)
./claude-daemon-manager.sh start --message "continue working on the React feature"
./claude-daemon-manager.sh start --at "09:00" --message "resume our Python project"

# Check daemon status
./claude-daemon-manager.sh status

# Live dashboard with real-time updates
./claude-daemon-manager.sh dash

# View logs
./claude-daemon-manager.sh logs

# Follow logs in real-time
./claude-daemon-manager.sh logs -f

# Stop the daemon
./claude-daemon-manager.sh stop

# Restart the daemon (with same start/stop times if previously set)
./claude-daemon-manager.sh restart
./claude-daemon-manager.sh restart --at "10:00"  # new start time
./claude-daemon-manager.sh restart --at "09:00" --stop "17:00"  # new schedule

Live Dashboard 📊

The new live dashboard provides real-time monitoring of your Claude renewal status:

# Launch the interactive dashboard
./claude-daemon-manager.sh dash

Dashboard Features:

• 🔧 Daemon Status - Current state (WAITING/ACTIVE/STOPPED) with PID and timing details
• ⏱️ Progress Bar - Visual progress showing time until next renewal reset (color-coded)
• 📅 Today's Plan - Estimated renewal trigger times throughout the day
• 📝 Live Activity - Real-time log entries and recent daemon actions
• 🔄 Auto-Updates - Refreshes every minute automatically
• 🎯 Smart Layout - Clean interface with clear sections and formatting

Progress Bar Colors:

• 🟢 Green - More than 1 hour remaining
• 🟡 Yellow - 30-60 minutes remaining
• 🔴 Red - Less than 30 minutes remaining

Usage:

• Press Ctrl+C to exit the dashboard
• Dashboard updates automatically every 60 seconds
• Works only when daemon is running
• Shows "No renewal tracking" when no activity file exists

Example dashboard output:

╔══════════════════════════════════════════════════════════════════════════════╗
║                    Claude Auto-Renewal Dashboard                            ║
║                   Wednesday, August 06, 2025 - 16:54:07                   ║
╚══════════════════════════════════════════════════════════════════════════════╝

🔧 DAEMON STATUS:
  PID: 12345
  Status: ✅ ACTIVE - Auto-renewal monitoring enabled

⏱️  TIME TO NEXT RESET:
  ████████████████████████░░░░░░░░░░░░░░░░ 60% (1h 59m remaining)
  Next renewal at: 18:53

📅 TODAY'S RENEWAL PLAN:
  • 18:53 (NEXT)
  • 23:53

📝 RECENT ACTIVITY:
  [2025-08-06 16:53:20] Renewal successful!
  [2025-08-06 16:53:10] Starting Claude session for renewal...

How It Works

1. Monitors your Claude usage using ccusage (or time-based fallback)
2. Detects when your 5-hour block is about to expire
3. Waits until just after expiration (within scheduled hours)
4. Starts a minimal Claude session (custom message or random greeting)
5. Stops monitoring at configured stop time
6. Automatically restarts the next day at start time
7. Logs all activities for transparency

Custom Renewal Messages 💬

Default Behavior (without --message): The daemon automatically sends random greetings ("hi", "hello", "hey there", "good day", "greetings", "howdy", "what's up", "salutations") when renewing sessions. This is the original behavior and requires no configuration.

Custom Messages (with --message): You can optionally specify a custom message to maintain context when resuming work after rate limits:

# Use custom message for renewals
./claude-daemon-manager.sh start --message "continue working on the React feature"

# Combine with other options
./claude-daemon-manager.sh start --at "09:00" --stop "17:00" --message "resume our database optimization"

# The message persists across daemon restarts
./claude-daemon-manager.sh restart  # Still uses the previous custom message

# Clear custom message (return to random greetings)
./claude-daemon-manager.sh restart  # Without --message flag

Why use custom messages?

• Context Continuity: When rate-limited mid-task, resume with relevant context
• Project Tracking: Include project name for better session organization
• Task Resumption: Specify what you were working on before the limit
• Better History: More meaningful renewal entries in your Claude history

Example scenarios:

• Working on a feature: --message "continue implementing the auth system"
• Debugging session: --message "resume debugging the memory leak issue"
• Learning session: --message "continue the Python tutorial"
• Code review: --message "resume reviewing the pull request"

Clock-only Mode

By default, the daemon uses ccusage for accurate timing information. However, you can bypass ccusage entirely and rely solely on clock-based timing:

# Start with clock-only mode
./claude-daemon-manager.sh start --at "09:00" --stop "17:00" --disableccusage

When --disableccusage is used:

• 🚫 No ccusage dependency - Works without ccusage installed
• ⏰ Clock-based timing - Relies on 5-hour intervals from last activity
• 📝 Clear logging - Shows "⚠️ ccusage DISABLED - Using clock-based timing only"
• 🎯 Same functionality - All scheduling features still work

This mode is useful when:

• You don't want to install ccusage
• ccusage is causing issues on your system
• You prefer simpler time-based renewal checking
• You're in a restricted environment where ccusage can't run

💡 Avoid Session Burning

Problem: Starting daemon at wrong time wastes your 5-hour block

# BAD: Start daemon at 6am but want to code 9am-2pm = 3 hours wasted!
./claude-daemon-manager.sh start

# GOOD: Schedule daemon to start monitoring at 9am
./claude-daemon-manager.sh start --at "09:00"
# Your 5-hour block: 9am-2pm (perfect timing!)

# BETTER: Schedule both start and stop times for daily work schedule
./claude-daemon-manager.sh start