A terminal paddle game

Quiet, fast, and
honest paddleball.

A physics-based paddle game that lives in your terminal. Sub-stepped collisions that never glitch, five restrained themes, and a paddle that follows your mouse. One binary, no clutter.

$ curl -fsSL https://raw.githubusercontent.com/subhadeeproy3902/paddle-ball/main/install.sh | bash
Install ↓ View source
What's inside

Built to feel right, not to shout.

Every part of the game is tuned for a calm, precise feel — restrained color, smooth motion, and physics you can trust.

01

Sub-stepped physics

The ball moves in collision-safe sub-steps, so it never tunnels through a wall or resets mid-rally — even at top speed.

02

Spring-driven paddle

A harmonica spring chases your input for weighty, fluid control. Keys, or just move your mouse — the paddle follows.

03

Five quiet themes

Claude, Mono, Nord, Moss, and Ember. Each leans on a single accent — no rainbow, no neon, no glow.

04

Power-ups & phases

Six power-ups and five escalating difficulty phases in Arcade and Zen, from a gentle warm-up to genuinely insane.

05

Score history

Every run is saved to a local JSON store with a built-in leaderboard, per-mode filters, and lifetime stats.

06

Single binary

Pure Go, zero runtime dependencies. Install with one command, or grab it from Homebrew, Scoop, apt, or Docker.

See it run

The real thing, in your terminal.

An actual frame from Arcade mode — live HUD, a power-up timer, the ball's trail, and the coral paddle. Rendered, not mocked.

paddle-ball running in a terminal: Arcade mode showing score 128, phase 4 Blazing, three lives, a 17 streak, the ball and its trail, the coral paddle, and an active Fire Paddle power-up.
paddle-ball · Arcade · Claude theme
Four ways to play

Pick a pace.

01

Classic

One life, pure score chase. Every miss ends the run.

02

Arcade

Three lives and the full power-up roster to fight for.

03

Zen

Endless rally, no game over. Just the bounce.

04

Time Trial

A sixty-second sprint for the highest score you can stack.

Install

One command, any platform.

macOS / Linux 
# one-line install
curl -fsSL https://raw.githubusercontent.com/subhadeeproy3902/paddle-ball/main/install.sh | bash
Homebrew 
brew tap subhadeeproy3902/paddle-ball
brew install paddle-ball
Go 
go install github.com/subhadeeproy3902/paddle-ball@latest
Docker 
docker run --rm -it ghcr.io/subhadeeproy3902/paddle-ball:latest
Controls

Everything from the keyboard.

← →move the paddle
mousepaddle follows the cursor
P · Spacepause / resume
Tcycle theme
Mtoggle sound
Cclear score history
Rrestart
Q · Ctrl+Cquit
Questions

Good to know.

What is paddle-ball?

A free, open-source, minimalist paddleball game that runs entirely in your terminal. It pairs sub-stepped collision physics with a spring-driven paddle you steer with the keyboard or mouse, five restrained themes, four game modes, sound, and a persistent score history.

How do I install it?

On macOS or Linux: curl -fsSL https://raw.githubusercontent.com/subhadeeproy3902/paddle-ball/main/install.sh | bash. Or use Homebrew (brew install paddle-ball), Go (go install github.com/subhadeeproy3902/paddle-ball@latest), Docker, or a prebuilt binary from the releases page.

Which operating systems are supported?

Prebuilt binaries ship for macOS, Linux, and Windows on amd64 and arm64, plus .deb, .rpm, and .apk packages and a Docker image. Anything that can run a single Go binary in a UTF-8 terminal works.

Is it free and open source?

Yes — MIT-licensed and free. The full source lives on GitHub.