ccblocks

░░      ░░░      ░░       ░░  ░░░░░░░      ░░░      ░░  ░░░░  ░░      ░░
▒  ▒▒▒▒  ▒  ▒▒▒▒  ▒  ▒▒▒▒  ▒  ▒▒▒▒▒▒  ▒▒▒▒  ▒  ▒▒▒▒  ▒  ▒▒▒  ▒▒  ▒▒▒▒▒▒▒
▓  ▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓       ▓▓  ▓▓▓▓▓▓  ▓▓▓▓  ▓  ▓▓▓▓▓▓▓     ▓▓▓▓▓      ▓▓
█  ████  █  ████  █  ████  █  ██████  ████  █  ████  █  ███  ████████  █
██      ███      ██       ██       ██      ███      ██  ████  ██      ██

Time-shift Claude sessions to match your working hours

Simple concept:

• Scheduled trigger: claude -p --safe-mode --model haiku ...
• Starts new 5-hour block automatically
• Runs through Claude subscription auth only
• Refuses API-key and third-party provider auth
• Zero maintenance after setup

Example:

• Without ccblocks: Start coding at 9 AM → hit limits at 10 AM → locked out until 2 PM
• With ccblocks: Trigger at 6 AM → start coding at 9 AM → spans multiple blocks → more headroom

Token cost: intentionally minimal. ccblocks always uses Claude Code's haiku model alias with a tiny one-turn prompt.

Each Claude trigger starts a 5-hour usage window. This is the fundamental constraint that shapes optimal scheduling:

• Maximum useful triggers: 4 per day (24h ÷ 5h = 4.8)
• Minimum spacing: 5 hours between triggers
• Optimal coverage: 20 hours/day with 4 strategically-placed triggers

Why not more triggers? Triggers within an active 5-hour window don't start new blocks—they're wasted. A 5th trigger would overlap an existing window without extending coverage.

Visualising the 247 Max schedule (optimal):

00:00 ━━━━━ 05:00 (gap) 06:00 ━━━━━ 11:00 (gap) 12:00 ━━━━━ 17:00 (gap) 18:00 ━━━━━ 23:00 (gap)
      5h                      5h                      5h                      5h

Result: 20 hours of coverage with 4 hours of strategic gaps (5-6 AM, 11 AM-12 PM, 5-6 PM, 11 PM-12 AM).

Key insight: More triggers ≠ more coverage. Strategic placement maximises available hours while respecting the 5-hour window constraint.

Important: If you use Claude during a scheduled gap, you'll immediately trigger a new 5-hour block regardless of your ccblocks schedule. This is why it's best to align your schedule with your daily routine: plan gaps during lunch, gym, meetings, or quiet time when you won't be coding.

# Install via Homebrew
brew install designorant/tap/ccblocks

# Run setup
ccblocks setup

Homebrew 6 note: the fully-qualified brew install designorant/tap/ccblocks automatically trusts the formula. If you later see an untrusted tap warning (for example on brew upgrade), trust the tap once with brew trust designorant/tap.

ccblocks is currently distributed via a personal Homebrew tap. Once the project reaches sufficient popularity, it will be submitted to the official Homebrew repository for easier installation (just brew install ccblocks).

Requirements for official inclusion (per Homebrew guidelines):

• ≥30 forks, ≥30 watchers, or ≥75 stars

If you find ccblocks useful, starring the repository helps us reach this milestone!

Platform Support: macOS and Linux only. Windows is not currently supported (contribute!).

247 Maximum Coverage (Recommended)

Triggers: 12 AM, 6 AM, 12 PM, 6 PM daily (4 triggers)
Coverage: 20 hours/day (optimal)
Gaps: 5-6 AM, 11 AM-12 PM, 5-6 PM, 11 PM-12 AM (4h total)

Work Hours Only

Triggers: 9 AM, 2 PM on weekdays (2 triggers)
Coverage: 10 hours/day (9 AM - 7 PM)
Gaps: 7 PM - 9 AM (14h)

Night Owl

Triggers: 6 PM, 11 PM daily (2 triggers)
Coverage: 10 hours/day (6 PM - 4 AM)
Gaps: 4 AM - 6 PM (14h)

ccblocks setup                         # Install and configure
ccblocks status                        # Show schedule and recent activity
ccblocks schedule list                 # List available schedules
ccblocks schedule apply <name>         # Apply preset schedule (247, work, night)
ccblocks schedule apply custom         # Interactive custom schedule
ccblocks schedule apply custom 0,8,16  # Custom schedule with hours
ccblocks pause                         # Vacation mode
ccblocks resume                        # Resume after vacation
ccblocks uninstall                     # Complete removal

Does this bypass Claude's rate limits? No. Your subscription limits still apply. This optimizes when your 5-hour windows start.

Does this use API credits? No. ccblocks is designed for Claude subscription users. It refuses to trigger when API-key or third-party provider credentials are present.

How much does this cost in tokens? Each trigger sends a tiny one-turn prompt to Claude Code's cheapest model alias, haiku, and expects a short acknowledgement.

Can I customise the schedule? Yes! See Configuration for preset schedules and custom schedule options.

Why not just use cron or a bash loop?

You can - many users successfully schedule triggers with:

• Cron: Simple, but limited logging and error handling
• Bash loop: Works in tmux/screen, but manual recovery if it dies

ccblocks provides:

• Reliability: Automatic restart, survives reboots
• Management: Easy schedule changes, pause/resume, status monitoring
• Best practices: OS-native service managers (LaunchAgent/systemd)
• Observability: System logs, failure notifications

Architecture:

• macOS: LaunchAgent (~/Library/LaunchAgents/ccblocks.plist)
• Linux: systemd user service (~/.config/systemd/user/ccblocks@.service)

Trigger mechanism:

1. LaunchAgent/systemd timer fires at scheduled time
2. Executes ccblocks-daemon in your user session
3. Confirms Claude subscription auth is active and API/provider credentials are not present
4. Runs claude -p --safe-mode --model haiku --max-turns 1 --tools "" --output-format text ...
5. New 5-hour block starts immediately
6. Logs success/failure to system log

# Check scheduler status
ccblocks status

# View system logs
log show --last 1d --info --predicate 'eventMessage CONTAINS[c] "ccblocks"'    # macOS
journalctl --user -t ccblocks -n 50                       # Linux

# Manual test trigger
ccblocks trigger

Change schedule:

See Schedules for available presets (247, work, night).

ccblocks schedule apply <name>             # Apply preset schedule
ccblocks schedule apply custom             # Interactive custom schedule
ccblocks schedule apply custom 0,8,16      # Custom with specified hours

Custom schedule examples:

• 0,8,16 → 15 hours/day coverage (midnight, 8 AM, 4 PM)
• 9,15,21 → 15 hours/day coverage (9 AM, 3 PM, 9 PM)
• 0,12 → 10 hours/day coverage (midnight, noon)
• 0,6,12,18 → 20 hours/day coverage (optimal 4 triggers)

Validation rules:

• Minimum 2 triggers, maximum 4 triggers per day
• Triggers must be ≥5 hours apart (Claude's block duration)
• Hours in 24-hour format (0-23)

Vacation mode:

ccblocks pause    # Disable all triggers
ccblocks resume   # Re-enable schedule

Your schedule is preserved when paused.

Scheduler not running:

macOS:

launchctl list | grep ccblocks           # Should show loaded
ls ~/Library/LaunchAgents/ccblocks.plist # Should exist
ccblocks status                          # Check detailed status

Linux:

systemctl --user list-timers | grep ccblocks # Should show active
systemctl --user daemon-reload               # Reload if needed
ccblocks status                              # Check detailed status

Claude CLI issues:

which claude          # Verify installation
echo "test" | claude  # Test authentication

ccblocks requires Claude CLI to be installed and authenticated.

Logs and configuration:

• Config directory: ~/.config/ccblocks/
• macOS logs: Use log show (see Status & Monitoring above)
• Linux logs: Use journalctl (see Status & Monitoring above)

Homebrew automatically removes schedulers when uninstalling:

# Uninstall package (automatically cleans up schedulers)
brew uninstall ccblocks

# Optional: Remove user configuration
rm -rf ~/.config/ccblocks

• Questions: Ask in GitHub Discussions
• Issues: Report bugs on GitHub Issues
• Contact: @designorant on X or @designorant.com on BlueSky

Contributions are welcome! For local development, testing, and contribution guidelines, see CONTRIBUTING.md.

MIT © @designorant