claude-auto

README

claude-auto

Automatic rate limit handler for Claude CLI. Wraps the claude command in a PTY, detects rate limit messages, waits, and automatically sends "continue" to resume your session.

Features

• ✅ Transparent PTY wrapper - Works exactly like running claude directly
• ✅ Smart rate limit detection - 7 regex patterns to catch various formats
• ✅ Intelligent wait times - Parses actual wait times from messages
• ✅ Exponential backoff - Automatically increases wait time if parsing fails
• ✅ Jitter - Adds random delay to avoid thundering herd
• ✅ Cooldown - Prevents spamming continue commands
• ✅ Terminal features - Full support for ANSI colors, terminal resize, raw mode
• ✅ Cross-platform - Works on macOS, Linux, and Windows (Go-based)

Installation

Prerequisites

• Claude CLI - Install with npm install -g @anthropic-ai/claude-code
• Authenticate: claude auth login

Quick Install (Recommended)

One-line install script for macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/darrillaga/claude-auto/main/install.sh | bash

Platform-Specific Install

macOS (Apple Silicon)

curl -fsSL https://github.com/darrillaga/claude-auto/releases/latest/download/claude-auto-darwin-arm64.tar.gz | tar -xz
sudo mv claude-auto-darwin-arm64 /usr/local/bin/claude-auto

macOS (Intel)

curl -fsSL https://github.com/darrillaga/claude-auto/releases/latest/download/claude-auto-darwin-amd64.tar.gz | tar -xz
sudo mv claude-auto-darwin-amd64 /usr/local/bin/claude-auto

Linux (x86_64)

curl -fsSL https://github.com/darrillaga/claude-auto/releases/latest/download/claude-auto-linux-amd64.tar.gz | tar -xz
sudo mv claude-auto-linux-amd64 /usr/local/bin/claude-auto

Linux (ARM64)

curl -fsSL https://github.com/darrillaga/claude-auto/releases/latest/download/claude-auto-linux-arm64.tar.gz | tar -xz
sudo mv claude-auto-linux-arm64 /usr/local/bin/claude-auto

Windows

Download from releases page, extract, and add to PATH.

Using Go

If you have Go installed:

go install github.com/darrillaga/claude-auto@latest

Build from Source

git clone https://github.com/darrillaga/claude-auto.git
cd claude-auto
go build -o claude-auto
sudo cp claude-auto /usr/local/bin/

Usage

Interactive mode

Run claude-auto with no arguments to start an interactive Claude session with automatic rate limit handling:

# Start interactive session
claude-auto

# With verbose logging
claude-auto --verbose

# Interactive mode automatically detects and resumes on rate limits

One-shot mode

Use -p for single prompt execution:

# One-shot execution
claude-auto -p "Write a function to parse JSON"

# With custom wait times
claude-auto --default-wait 15m -p "Long task"

With wrapper flags

Use -- to separate wrapper flags from Claude args:

claude-auto --verbose --default-wait 5m -- -p "Long task"

Configuration options

Flag	Env Var	Default	Description
--continue-text	CLAUDE_AUTO_CONTINUE_TEXT	continue	Text to send to resume
--default-wait	CLAUDE_AUTO_DEFAULT_WAIT	10m	Default wait if parsing fails
--cooldown	CLAUDE_AUTO_COOLDOWN	30s	Min time between continues
--jitter-min	CLAUDE_AUTO_JITTER_MIN	2s	Minimum jitter
--jitter-max	CLAUDE_AUTO_JITTER_MAX	10s	Maximum jitter
--max-buffer-bytes	CLAUDE_AUTO_MAX_BUFFER_BYTES	100000	Buffer size for parsing
--max-backoff	CLAUDE_AUTO_MAX_BACKOFF	60m	Maximum backoff duration
--log	CLAUDE_AUTO_LOG	stderr	Log file path
--verbose	CLAUDE_AUTO_VERBOSE	false	Enable verbose logging

Configuration file

Create a config file to avoid repeating flags. Files are checked in order:

1. ./.claude-auto.conf (project-specific, highest priority)
2. ~/.claude-auto.conf (global defaults)

Format (simple KEY=VALUE):

# ~/.claude-auto.conf - Global defaults
verbose=false
default-wait=15m
log=/tmp/claude-auto.log

# Claude flags to always pass (space-separated)
claude-flags=--dangerously-skip-permissions

# ./.claude-auto.conf - Project-specific overrides
verbose=true
claude-flags=--dangerously-skip-permissions --debug

Precedence (lowest to highest):

1. Hardcoded defaults
2. Global config file (~/.claude-auto.conf)
3. Local config file (./.claude-auto.conf)
4. Environment variables (CLAUDE_AUTO_*)
5. CLI flags (--verbose, etc.)

Features:

• Comments start with #
• Quoted values supported: log="/path/with spaces"
• Unknown keys are ignored (forward compatibility)
• claude-flags are prepended to command-line args

Example usage with config:

# Create global config once
cat > ~/.claude-auto.conf << EOF
verbose=false
default-wait=10m
claude-flags=--dangerously-skip-permissions
EOF

# Now run without flags
claude-auto                     # Interactive with config
claude-auto -p "task"           # One-shot with config
claude-auto --verbose           # Override verbose from config

Examples

# Verbose mode
claude-auto --verbose -p "Complex task"

# Custom wait time and log file
claude-auto --default-wait 15m --log /tmp/claude.log -p "Task"

# Environment variables
export CLAUDE_AUTO_VERBOSE=true
export CLAUDE_AUTO_DEFAULT_WAIT=5m
claude-auto -p "Task"

How it works

1. PTY wrapper: Spawns claude in a pseudo-terminal (PTY)
2. I/O relay: Forwards stdin → PTY and PTY → stdout transparently
3. Buffer monitoring: Maintains rolling buffer of output (100KB default)
4. Rate limit detection: Every 500ms, checks buffer for rate limit patterns
5. Smart scheduling: Parses wait time or uses default with backoff
6. Auto-resume: Waits until scheduled time + jitter, then sends "continue"

Rate limit patterns detected

The parser recognizes these formats:

1. try again in X seconds/minutes/hours
2. retry after: Xs or retry after X seconds
3. available at HH:MM (local time)
4. available at YYYY-MM-DD HH:MM
5. available at 2026-01-27T18:34:56Z (ISO 8601)
6. wait X seconds/minutes/hours
7. Generic: rate limit or usage limit

Development

Project structure

claude-auto/
├── main.go          # Main orchestration
├── config.go        # Config parsing
├── logger.go        # Thread-safe logging
├── parser.go        # Rate limit detection
├── resumer.go       # Auto-resume logic
├── pty.go           # PTY handler
├── parser_test.go   # Parser unit tests
└── go.mod           # Dependencies

Running tests

# Unit tests
go test -v

# Verification script
go run verify_detection.go parser.go

# Build
go build -o claude-auto

Key dependencies

• github.com/creack/pty - PTY handling
• golang.org/x/term - Terminal control (raw mode, resize)

Limitations

• Requires claude to be in PATH
• Rate limit detection depends on message format
• Cannot detect rate limits in binary/image output

Troubleshooting

"claude command not found"

• Make sure Claude CLI is installed and in PATH
• Run which claude to verify

"inappropriate ioctl for device"

• This warning is normal when stdin/stdout are not a terminal (e.g., piped input)
• PTY still works, just terminal resize and raw mode are unavailable

Auto-resume not working

• Enable verbose mode: --verbose
• Check logs for "Rate limit pattern matched"
• Verify the output matches one of the supported patterns

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick start:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Follow Go style guidelines
5. Submit a pull request

Documentation

• CHANGELOG.md - Version history and changes
• CONTRIBUTING.md - Contribution guidelines
• LICENSE - MIT License

Links

• GitHub Repository
• Issues
• Releases
• Claude CLI

License

MIT License - see LICENSE file for details.

Copyright © 2026 David Arrillaga

Author

Created by David Arrillaga

If you find this tool helpful, please ⭐ star the repository!