courtside

README

🏀 Courtside

A minimalist terminal UI (TUI) for following NBA games in real-time — live scores, play-by-play events, and box score stats, all without leaving your terminal.

Inspired by Golazo — adapted for basketball.

[!NOTE] This project is under active development. See the roadmap for what's coming.

Features

• Live updates — scores, fouls, timeouts, and substitutions with automatic polling
• Box score stats — FG%, rebounds, assists, steals, blocks, turnovers in a focused dialog
• Finished games — results from today, last 3 days, or last 5 days
• Conference filtering — Eastern and Western, with playoff series support
• Highlight links — links to r/nba highlights
• Desktop notifications — for key moments during live games

What's Different from Golazo?

	Golazo	Courtside
Sport	Football/Soccer	Basketball (NBA)
Data source	FotMob API	NBA Stats API
Game structure	2 halves (45 min)	4 quarters (12 min) + OT
Score display	2-1	105-98
Live time	45+2'	Q3 2:34
Events	Goals, cards, subs	Field goals, fouls, timeouts
Competitions	50+ leagues worldwide	NBA (East/West) + playoffs
Highlights	r/soccer	r/nba

Installation

Build from source

git clone https://github.com/gabriel7419/courtside.git
cd courtside

# Build it
make build

# Run it
./courtside

Alternatively, you can install it globally via make install or go install ./cmd/....

Usage

courtside

# Or use the make command
make run

# Run with mock data (useful during the off-season or when no games are live)
courtside --mock
# or: make mock

Navigation: ↑/↓ or j/k to move, Enter to select, / to filter, Tab to switch pane, Esc to go back, q to quit.

Views:

• Today's games — live and upcoming games
• Finished games — recent results (last 3 or 5 days)
• Settings — filter by conference, toggle notifications

Docs

• Quick Start — set up your development environment
• Supported Teams — all 30 NBA teams by conference and division
• Notifications — desktop notification setup
• API Reference — NBA Stats API endpoints and response format
• Implementation Plan — full roadmap across 7 phases

Roadmap

• Project planning and documentation
• NBA API integration (internal/nba/)
• List today's games
• Game details view
• Live game polling
• Statistics dialog
• r/nba highlights integration
• Desktop notifications
• Playoff bracket view
• WNBA support

Contributing

See CONTRIBUTING.md for workflow, code guidelines, and what currently needs help.

Credits

Courtside is a fork/adaptation of Golazo by @0xjuanma.

Built with Bubble Tea, Lip Gloss and Bubbles by Charm.

License

MIT — see LICENSE for details.

---

Made with ❤️ for basketball and terminal enthusiasts