# Claude Throttle - Cursor Rules

## Project Overview

Claude Throttle is an ultra-lightweight Python CLI tool (`pip install claude-throttle`) that tells users whether their Anthropic Claude usage is currently at 2x or 1x during the March 13-27, 2026 promotion.

## Architecture

- Python package using `src/` layout
- Entry point: `throttle` command maps to `claude_throttle.cli:main`
- Build system: hatchling via pyproject.toml
- Only external dependency: pytz

## File Responsibilities

- `src/claude_throttle/engine.py` - ALL time/date logic. Only file that imports pytz. Returns plain dicts.
- `src/claude_throttle/cli.py` - ALL terminal presentation. ANSI colors, formatting, printing. No business logic.
- `src/claude_throttle/__init__.py` - Version string and re-exports check_status for library use.
- `tests/test_engine.py` - Unit tests for engine. Uses fixed datetimes, never calls real clock.

## Promotion Rules (Hardcoded Constants)

- Promo window: March 13, 2026 00:00:00 ET to March 27, 2026 23:59:59 ET
- Peak (1x): Monday-Friday, 8:00 AM - 2:00 PM Eastern Time
- Off-Peak (2x): All other weekday hours
- Weekends (2x): All day Saturday and Sunday
- Eligible: Free, Pro, Max, Team plans (NOT Enterprise)
- 2x usage does NOT count toward weekly limits

## Code Constraints

- Zero dependencies beyond pytz. Do NOT add requests, click, rich, typer, or any other package.
- ANSI escape codes only for terminal colors. No curses, no rich, no blessed.
- Python 3.8+ compatible. No walrus operator, no match/case, no tomllib.
- Keep the entire tool under 300 lines total across all source files.
- check_status() must accept an optional datetime parameter for testability.
- All time comparisons happen in US/Eastern timezone.
- Never use the system's local timezone for logic. Always convert to ET first.

## Style

- Type hints on function signatures.
- Docstrings on every public function.
- No classes. Plain functions and dicts only.
- No global mutable state.

## Testing

- Tests use pytest.
- Always pass explicit datetimes to check_status() - never rely on the real clock.
- Test these scenarios: weekday peak, weekday off-peak (before 8AM), weekday off-peak (after 2PM), weekend, Friday evening countdown to Monday, before promo starts, after promo ends, exact boundary times (8:00 AM, 2:00 PM).

## Distribution

- Package must be publishable to PyPI with `python -m build && twine upload dist/*`
- The `throttle` command must work globally after `pip install claude-throttle`
