This script is particularly useful when using Claude Code for development in the following scenarios:

1. Task Interrupted by Usage Limits: When your Claude Code shows Claude usage limit reached. but your task is not yet completely finished
2. Automatic Task Resumption: Simply run claude-auto-resume in your project's root directory, and when the usage limit is lifted, the script will automatically let Claude Code continue executing your previously unfinished task
3. Custom Command Execution: Execute any shell command after waiting for usage limits, useful for restarting services, running builds, or processing data

Features

• 🔄 Automatically detects Claude CLI usage limits
• ⏰ Smart waiting with countdown display
• 🚀 Automatic task resumption
• 🔧 Custom command execution after wait periods
• 🛡️ Security warnings with cancellation options
• 🔗 Support for complex commands (pipes, redirections, operators)
• 🧪 Built-in test mode for development and validation
• 🖥️ Cross-platform support (Linux/macOS/Windows PowerShell)
• 📦 Zero external dependencies (only standard Unix tools required)

Installation

Linux/macOS installation steps are identical to the original upstream repository and are kept unchanged below.

method 1: using wget (Recommended)

wget -qO- https://raw.githubusercontent.com/terryso/claude-auto-resume/refs/heads/develop/claude-auto-resume.sh  | sudo tee /usr/local/bin/claude-auto-resume >/dev/null && sudo chmod +x /usr/local/bin/claude-auto-resume

method 2: using Makefile

# Global installation
sudo make install

# Install to custom location
sudo make install PREFIX=/opt/local

# Uninstall
sudo make uninstall

method 3: Manual Installation

# Copy to system path
sudo cp claude-auto-resume.sh /usr/local/bin/claude-auto-resume
sudo chmod +x /usr/local/bin/claude-auto-resume

# Or create symbolic link
sudo ln -s $(pwd)/claude-auto-resume.sh /usr/local/bin/claude-auto-resume

method 4: Direct Usage (No Installation)

# Make script executable
chmod +x claude-auto-resume.sh

# Run directly
./claude-auto-resume.sh

Windows (PowerShell)

These Windows steps are specific to this fork. Linux/macOS users should use the methods above.

# From the repo root
$dest = Join-Path $env:USERPROFILE "bin"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item .\claude-auto-resume.ps1, .\claude-auto-resume.cmd $dest

Ensure the destination folder is on your user PATH, then run:

claude-auto-resume --help

Notes:

• The .cmd wrapper lets you run claude-auto-resume directly from PowerShell or CMD.
• The wrapper uses pwsh if available, otherwise falls back to Windows PowerShell.

Usage

Windows uses the same command-line options and flags as Linux/macOS.

Basic Usage

# Start new session with default prompt "continue"
claude-auto-resume

# Start new session with custom prompt
claude-auto-resume "implement user authentication"

# Start new session with custom prompt using flag
claude-auto-resume -p "write unit tests"

# Continue previous conversation with custom prompt
claude-auto-resume -c "please continue the previous task"

# Continue previous conversation with custom prompt using flag
claude-auto-resume -c -p "resume where we left off"

# Execute custom command after wait period
claude-auto-resume -e "npm run dev"

# Execute custom command with alias flag
claude-auto-resume --cmd "python app.py"

# Show help
claude-auto-resume --help

Local Usage (Before Installation)

# Ensure script is executable
chmod +x claude-auto-resume.sh

# Start new session with default prompt
./claude-auto-resume.sh

# Start new session with custom prompt
./claude-auto-resume.sh "create login page"

# Continue previous conversation
./claude-auto-resume.sh -c "continue with the implementation"

# Execute custom command after wait period
./claude-auto-resume.sh -e "make build"

How It Works

1. Detect Limits: Execute claude -p 'check' command
2. Parse Output: Look for Claude AI usage limit reached|<timestamp> format messages
3. Calculate Wait Time: Calculate required wait time based on timestamp
4. Display Countdown: Show real-time remaining wait time
5. Auto Resume: Automatically execute either:
   • claude --dangerously-skip-permissions -p "<custom-prompt>" (new session, default)
   • claude -c --dangerously-skip-permissions -p "<custom-prompt>" (continue conversation with -c flag)
   • Custom shell command with -e/--execute or --cmd flags

Command Line Options

• No arguments: Start new session with default prompt "continue"
• Single argument: Start new session with custom prompt (e.g., claude-auto-resume "implement feature")
• -p, --prompt: Specify custom prompt with flag (e.g., claude-auto-resume -p "write tests")
• -c, --continue: Continue previous conversation (adds -c flag to claude command)
• -e, --execute: Execute custom shell command after wait period (e.g., claude-auto-resume -e "npm run dev")
• --cmd: Alias for -e/--execute (e.g., claude-auto-resume --cmd "python app.py")
• --test-mode: [DEV] Simulate usage limit with specified wait time in seconds
• -h, --help: Show help message and usage examples
• -v, --version: Show version information
• --check: Show system check information

Session Types

Start New Session (Default)

Uses claude without -c for fresh conversation:

claude-auto-resume                    # New session with "continue"
claude-auto-resume "new feature"      # New session with custom prompt
claude-auto-resume -p "write tests"   # New session with flag

Continue Previous Conversation

Uses claude -c to continue the last conversation:

claude-auto-resume -c "keep going"           # Continue with custom prompt
claude-auto-resume -c -p "resume work"       # Continue with flag

Execute Custom Commands

Execute any shell command after the wait period:

claude-auto-resume -e "npm run dev"                    # Start development server
claude-auto-resume --cmd "python app.py"               # Run Python application
claude-auto-resume -e "make build && ./app"            # Complex command with operators
claude-auto-resume -e "ls -la | grep '.js' | wc -l"    # Pipeline commands
claude-auto-resume -e "echo 'Step 1'; echo 'Step 2'"   # Multiple commands

Development and Testing

Use the built-in test mode for development and validation:

claude-auto-resume --test-mode 5 -e "echo 'Test command'"    # Test with 5-second wait
claude-auto-resume --test-mode 10 --cmd "npm run test"       # Test build process

Requirements

• Claude CLI: Must be installed and available in PATH
• Standard Unix Tools: grep, date, sleep, awk (usually pre-installed)
• Windows: PowerShell 5.1+ or PowerShell 7+ (when using the Windows script)

Security Considerations

Permission Bypass

This script uses --dangerously-skip-permissions to enable unattended operation. This means:

1. No interactive prompts: Claude will not ask for confirmation before executing commands
2. Automatic execution: File changes, system commands, and other operations run without user approval
3. Trust requirement: You must trust both the script and the prompt you provide

Best Practices

• Environment isolation: Use only in development/testing environments
• Prompt review: Carefully craft prompts to limit scope (e.g., "continue implementing the login function in src/auth.js")
• Command review: Verify custom commands are safe and appropriate for your environment
• Backup your work: Ensure you have version control or backups before running
• Monitor execution: Check the output to understand what actions were taken
• Limit scope: Use specific prompts/commands rather than open-ended ones

Error Handling

The script includes comprehensive error handling:

• Exit Code 1: Claude CLI execution failed
• Exit Code 2: Unable to extract valid resume timestamp
• Exit Code 4: Resume command execution failed

Testing

# Syntax check
make test

# Or use bash directly
bash -n claude-auto-resume.sh

Project Structure

claude-auto-resume/
├── claude-auto-resume.sh    # Main script
├── claude-auto-resume.ps1   # Windows PowerShell script
├── claude-auto-resume.cmd   # Windows wrapper
├── Makefile                 # Installation