Hoop Higher

Hoop Higher is a terminal game for NBA fans: you see one player's points from an NBA box score, then guess whether another player scored higher or lower.

It is quick to start, easy to play from the keyboard, and built around short runs that test your NBA instincts one matchup at a time.

Play

Run it without installing:

uvx hoop-higher

Or install the command:

uv tool install hoop-higher
hoop-higher

hoop-higher is the only supported command name.

How It Works

Each question gives you a player and their point total. Your job is to decide whether the next player scored more or fewer points in that same game context.

After every guess, Hoop Higher reveals the answer, updates your score, and moves to the next comparison. Runs are saved locally so you can track your best scores, streaks, and overall stats.

Game Modes

Controls

Hoop Higher starts in its dark theme. Press T on any screen to switch between the dark and light palettes; the choice is saved and restored on the next run.

Data

By default, Hoop Higher uses real NBA game data through nba_api and caches results locally so future runs are faster.

If the live NBA data source is slow or unavailable, you can still try the game instantly with mock data:

HOOPHIGHER_STATS_PROVIDER=mock uvx hoop-higher

Local scores, stats, and cached games are stored in your platform's per-user data directory (for example, ~/Library/Application Support/hoop-higher/hoophigher.db on macOS). Existing var/hoophigher.db databases remain in use so prior data is preserved. To use another location, set HOOPHIGHER_DATABASE_URL to a SQLite URL, such as sqlite:////absolute/path/to/hoophigher.db.

From Source

git clone https://github.com/Davi-Gurgel/hoop-higher.git
cd hoop-higher
uv sync --all-groups
uv run hoop-higher

Run tests:

uv run pytest

License

No license file is currently included in this repository.