feat: Show rate limit stats and reset time when limit reached

[rubenmarcus]

Summary

When ralph-starter hits API rate limits, display detailed stats and estimated time until reset so users know when they can continue.

Current Behavior

⚠ Claude rate limit reached

Your Claude session usage is at 100%.
Wait for your rate limit to reset, then run again:
  ralph-starter run

Desired Behavior

⚠ Claude rate limit reached

Rate Limit Stats:
  • Session usage: 100% (50,000 / 50,000 tokens)
  • Requests made: 127 this hour
  • Time until reset: ~47 minutes (resets at 04:30 UTC)

Session Progress:
  • Tasks completed: 3/5
  • Current task: "Add swarm mode CLI flags"
  • Branch: auto/github-54

To resume when limit resets:
  ralph-starter resume

Tip: Check your limits at https://claude.ai/settings

Implementation

Task 1: Rate Limit Detection

• Parse rate limit headers from Claude API responses
• Extract remaining tokens/requests
• Calculate reset time from headers

Task 2: Stats Display

• Create src/utils/rate-limit-display.ts
• Format usage percentage
• Show requests made this session
• Display time until reset (human readable)

Task 3: Session Context

• Show tasks completed vs total
• Display current task being worked on
• Show current git branch
• Integration with session.ts (feat: Add session pause/resume for rate limit recovery #79)

Task 4: Reset Time Calculation

• Parse x-ratelimit-reset header if available
• Fallback to estimation based on typical reset windows
• Show both local and UTC time

Task 5: Documentation

• Add rate limiting section to README.md
• Create docs/rate-limits.md for Docusaurus
• Document how to check limits
• Add troubleshooting tips

API Headers to Parse

x-ratelimit-limit: 50000
x-ratelimit-remaining: 0
x-ratelimit-reset: 1707112800
retry-after: 2820

Files to Create/Modify

• src/utils/rate-limit-display.ts (new)
• src/loop/executor.ts (add rate limit handling)
• src/commands/auto.ts (display on limit)
• README.md (add rate limits section)
• docs/rate-limits.md (new - Docusaurus)

Related

• feat: Add session pause/resume for rate limit recovery #79 - Session pause/resume feature
• Works together with resume command to provide seamless recovery

[rubenmarcus]

Automated PR created: multivmlabs/ralph-starter#121

Generated by ralph-starter auto mode