hypercar-colorscripts

Random hypercar art in your terminal.
One of the first open-source projects to bring curated automotive art to terminal startup screens.
690 curated cars across 29 brands, verified free-license, mixed with system info via fastfetch.

demo.mp4

Install · Usage · Vintage · Contribute · Troubleshooting · License

What is this?

Inspired by pokemon-colorscripts, hypercar-colorscripts prints a random hypercar every time you open a terminal — a Ferrari F40 one time, a Bugatti Chiron the next, a McLaren F1 the one after. Sourced from Wikimedia Commons, backgrounds cleanly removed, letterboxed to a consistent 512×256 canvas.

In image-capable terminals (Kitty, Ghostty, WezTerm, iTerm2), you see a real photo of the car via the Kitty graphics protocol.
In every other terminal (git bash, GNOME Terminal, plain xterm), you see hand-rendered ANSI block art of the same car.
If you have pokemon-colorscripts installed too, both mix ~50/50 in your terminal startup (opt-in during install, toggle with --set-mix on|off).

The tool is a single Go binary. Nothing runs in the background. Nothing writes outside $HOME unless you install with --system.

Features

690 cars, 29 brands, 1940s → 2020s. Ferrari, Lamborghini, McLaren, Pagani, Koenigsegg, Bugatti, Porsche, Rolls-Royce, Aston Martin, Lotus, Rimac, Hennessey, plus Japanese and American icons.
Every image is free-license. CC0, CC BY, CC BY-SA, GFDL, Public Domain, or Free Art. Every image ships with a JSON attribution file. See CREDITS.md.
Smart lookup. Type --car chiron or --car "rolls royce ghost" or --car "porsche 911" — it resolves aliases, matches by tokens, corrects typos, and shows a numbered picker when multiple cars fit.
Real images or ANSI fallback, chosen automatically based on your terminal's capabilities. Force one mode with --set-mode auto|ansi.
Pokemon mixing is opt-in. The installer asks; you can toggle later with --set-mix on|off.
Vintage cars are opt-in. Default install is modern (2000+). Add pre-2000 cars any time with --install-vintage or ./install-vintage.sh.
--doctor health check tells you exactly what's wrong when something isn't working.
Contributor scripts for adding new cars (add_car.py) or replacing existing images (manual_override.py) with automated background removal and license validation.
Zero background daemons, zero telemetry, zero non-standard paths. Uses XDG directories.

Preview

Terminal startup — random car with fastfetch beside it

Named lookup — hypercar-colorscripts --car "Lamborghini Revuelto"

Numbered picker — hypercar-colorscripts --car "porsche 911"

Multiple matches for "porsche 911":
   1) porsche_911_carrera_992    911 Carrera (992)             2019–2024
   2) porsche_911_gt3_rs_992     911 GT3 RS (992)              2022–2024
   3) porsche_911_gt2_rs_991     911 GT2 RS (991.2)            2018
   4) porsche_911_gt3_992        911 GT3 (992)                 2021–2024
   5) porsche_911_turbo_s_992    911 Turbo S (992)             2020–2024
   6) porsche_911_dakar          911 Dakar                     2022–2024
   7) porsche_911_r_991          911 R (991.2)                 2016
   8) porsche_911_carrera_rs_2_7 911 Carrera RS 2.7            1973
   9) porsche_911_carrera_964    911 Carrera (964)             1989–1994
  10) porsche_911_gt1_strassenversion 911 GT1 Straßenversion   1998

Pick [1-10, q to quit]:

List brands — hypercar-colorscripts --list-brands

  Aston Martin       28 cars   1948–2024
  Audi Sport         19 cars   1980–2024
  BMW M              22 cars   1972–2024
  Bugatti            15 cars   1909–2024
  Ferrari            91 cars   1947–2024
  Ford                9 cars   1964–2017
  Koenigsegg         12 cars   1994–2024
  Lamborghini        73 cars   1963–2024
  ...

29 brands, 690 cars total

Prerequisites

Tool	Required?	Purpose
`chafa`	required	image rendering + ANSI generation
`fastfetch`	recommended	system info beside the car
`pokemon-colorscripts`	optional	enables 50/50 pokemon+car mix at terminal startup
`python3`	required for install	asset filtering, contributor scripts
`git`	required	to clone the repo

Install commands per distribution:

Fedora / RHEL

sudo dnf install chafa fastfetch python3 git

Debian / Ubuntu

sudo apt install chafa fastfetch python3 git

Arch / Manjaro

sudo pacman -S chafa fastfetch python git

macOS (Homebrew)

brew install chafa fastfetch python git

pokemon-colorscripts is not in any distro repo. Install separately if you want the mixing feature — see the project page.

Quick install

git clone https://github.com/Tirthraj-Raval/hypercar-colorscripts.git
cd hypercar-colorscripts/cli
make build
./install.sh

The installer asks these questions:

Rendering mode — auto (image when possible, ANSI otherwise) or ansi (always ANSI)
Include vintage cars? — pre-2000 cars, ~15 MB extra (default: no; add later with --install-vintage or ./install-vintage.sh)
Mix pokemon with cars? — only asked if pokemon-colorscripts is installed (toggle later with --set-mix on|off)
Which shell rc files — installs into your login shell's rc by default; offers to also install into secondary shells if present

Open a new terminal — you should see a car (or a pokemon, if you enabled mixing).

Verify the install:

hypercar-colorscripts --doctor

Green checks mean everything is set up. Yellow circles mark optional things missing. Red X's tell you what to fix.

Usage

Random car (the default)

hypercar-colorscripts

This is what runs at terminal startup. Bare invocation picks a random car from all installed cars.

Named car — smart lookup

Any of these work:

hypercar-colorscripts --car chiron              # alias → bugatti_chiron
hypercar-colorscripts --car "rolls royce ghost" # alias → rr_ghost_2nd_gen
hypercar-colorscripts --car F40                 # normalized → ferrari_f40
hypercar-colorscripts --car "huayra bc"         # tokens → pagani_huayra_bc
hypercar-colorscripts --car bugati_chiron       # typo → bugatti_chiron (Levenshtein)
hypercar-colorscripts --car "porsche 911"       # ambiguous → picker

The matcher tries these strategies in order and stops at the first hit: exact slug, alias map, case-insensitive slug, normalized slug, model-field match, token overlap, edit distance. If several cars tie, you get a numbered picker.

Filter and roll

hypercar-colorscripts --brand Ferrari              # random Ferrari
hypercar-colorscripts --brand Lamborghini --decade 1980s
hypercar-colorscripts --category Hypercar
hypercar-colorscripts --powertrain "V12 NA"
hypercar-colorscripts --country Italy
hypercar-colorscripts --decade 2020s --category Hypercar

Filters combine — the last example rolls a random 2020s hypercar.

Discovery

hypercar-colorscripts --list-brands       # every brand with car count + year range
hypercar-colorscripts --list-decades      # 1940s..2020s with vintage/modern label
hypercar-colorscripts --list-categories   # hypercar, supercar, GT, muscle, etc.
hypercar-colorscripts --search chiron     # substring search across slugs

Info and attribution

hypercar-colorscripts --info ferrari_f40
# Prints: brand, model, years, category, powertrain, country

hypercar-colorscripts --license ferrari_f40
# Prints: license, author, source URL, license URL

--info and --license accept the same smart matching as --car, so --info chiron works too.

Toggle rendering mode

If you picked auto at install but you're on a terminal that doesn't render images well, switch to ANSI:

hypercar-colorscripts --set-mode ansi
# open a new terminal — now shows ANSI text art everywhere

Switch back:

hypercar-colorscripts --set-mode auto

Toggle pokemon mixing

hypercar-colorscripts --set-mix off   # cars only
hypercar-colorscripts --set-mix on    # 50/50 mix (requires pokemon-colorscripts)

Health check

hypercar-colorscripts --doctor

Reports:

System dependencies (chafa, fastfetch, pokemon-colorscripts)
Terminal graphics-protocol support
Config file location and contents
Manifest integrity + asset file counts
Shell rc integration status
Effective pokemon-mixing state (combining pokemon-colorscripts availability, shell block presence, and pokemon_mix config)

Use this first when troubleshooting.

Complete command reference

Command	What it does
`hypercar-colorscripts`	Random car
`--car <name>`	Show a specific car (smart matching)
`--brand <name>`	Filter by brand
`--decade <year>s`	Filter by decade (e.g. `1980s`, `2020s`)
`--category <cat>`	Filter by category
`--powertrain <pt>`	Filter by powertrain
`--country <name>`	Filter by manufacturer's country
`--search <term>`	Substring search across slugs
`--info <name>`	Show car metadata
`--license <name>`	Show image attribution
`--list-brands`	List all brands with counts
`--list-decades`	List all decades with counts
`--list-categories`	List all categories with counts
`--set-mode auto\|ansi`	Change default rendering mode
`--set-mix on\|off`	Toggle pokemon mixing in shell startup
`--install-vintage`	Add pre-2000 cars (needs source repo)
`--uninstall-vintage`	Remove pre-2000 cars (self-contained)
`--doctor`	Environment health check
`--no-newline`	Suppress trailing newline (for shell prompts)
`--data-dir <path>`	Override the data directory
`--help`	Full CLI help

Vintage cars

Vintage = pre-2000. Off by default because most people want modern cars, but easy to add or remove anytime — either from the binary or from the cloned source repo.

From the installed binary

Add vintage cars:

hypercar-colorscripts --install-vintage

The binary looks for your source clone at these locations, in order:

$HYPERCAR_SRC (if set)
Current directory
~/hypercar-colorscripts, ~/car-test/hypercar-colorscripts, ~/projects/hypercar-colorscripts, ~/src/hypercar-colorscripts, ~/Documents/hypercar-colorscripts, ~/Downloads/hypercar-colorscripts

If found, it runs install-vintage.sh automatically. If not found, it prints clone instructions with the HYPERCAR_SRC escape hatch.

Remove vintage cars:

hypercar-colorscripts --uninstall-vintage

This is fully self-contained — no source repo needed. It reads the installed manifest, removes pre-2000 cars, deletes their asset files, and updates the manifest.

From the source repo

Same functionality via shell scripts, useful if the binary isn't installed yet or if you prefer scripts:

cd path/to/hypercar-colorscripts/cli
./install-vintage.sh       # add vintage
./uninstall-vintage.sh     # remove vintage

Terminal support

Terminal	Rendering	Notes
Kitty	Real image	Reference platform
Ghostty	Real image	Kitty-compatible graphics
WezTerm	Real image	Detected via `TERM_PROGRAM`
iTerm2 (macOS)	Real image	Kitty-compatible
GNOME Terminal	ANSI text	Falls back cleanly
Konsole	ANSI text	Falls back cleanly
xterm	ANSI text	Falls back cleanly
git bash (Windows)	ANSI text	Falls back cleanly
WSL2 + Windows Terminal	ANSI text	No image protocol available
macOS Terminal.app	ANSI text	Falls back cleanly

Detection is automatic and happens at every terminal startup. No config needed.

Shell integration

install.sh writes a marker-bracketed block into your .zshrc (or .bashrc, or both, depending on what you pick):

# >>> hypercar-colorscripts >>>
# ... 30 lines of portable shell that:
#   - reads default_mode and pokemon_mix from config.json
#   - detects terminal graphics-protocol support at runtime
#   - rolls ~50% pokemon (if enabled AND pokemon-colorscripts installed), else car
#   - picks image or ANSI based on terminal + mode
# <<< hypercar-colorscripts <<<

The block is portable — same code works in both bash and zsh. Uninstall removes it byte-for-byte with backups. Any existing pokemon-colorscripts startup line gets commented with a marker at install and un-commented at uninstall.

Nothing else in your rc file is touched. Ever.

Configuration

Location: ~/.config/hypercar-colorscripts/config.json

{
  "data_dir": "/home/you/.local/share/hypercar-colorscripts",
  "default_mode": "auto",
  "pokemon_mix": true,
  "with_pokemon": false,
  "pokemon_ratio": 0.5,
  "show_attribution": false
}

Field	Purpose	Values
`data_dir`	Where the manifest and assets live	absolute path
`default_mode`	Rendering preference for terminal startup	`"auto"`, `"ansi"`
`pokemon_mix`	Whether the shell block mixes pokemon 50/50	`true`, `false`
`with_pokemon`	Deprecated, unused	leave as `false`
`pokemon_ratio`	Reserved for future use	`0.0` – `1.0`
`show_attribution`	Print image credit under each car	`true`, `false`

Prefer editing via --set-mode and --set-mix when possible.

Contributing

Contributions are welcome — new cars, replacement images, common-name aliases, translations, bug fixes.

Adding a new car

Find a photo on Wikimedia Commons with a safe license (CC0, CC BY, CC BY-SA, GFDL, Public Domain, Free Art). Not sure what's safe? The script will reject unsafe licenses.
Copy the direct file URL (right-click the image → "Copy image address").
Run:

python scripts/add_car.py \
  --slug ferrari_f80 \
  --brand Ferrari --model "F80" \
  --start-year 2024 --end-year 2025 \
  --category Hypercar --powertrain "V6 Hybrid" \
  --image-url https://upload.wikimedia.org/.../F80.jpg \
  --license "CC BY-SA 4.0" \
  --author "Photographer Name" \
  --source-url https://commons.wikimedia.org/wiki/File:F80.jpg

Or run without args to be prompted interactively. Or batch-add many cars from a pipe-delimited file with --batch new_cars.txt.

The script downloads the image, removes the background with rembg, letterboxes to 512×256, generates ANSI art with chafa, writes the license JSON, and inserts the entry into data/car_database_v2.txt.

After adding cars:

python scripts/audit_licenses.py     # confirms every license is safe
python scripts/build_manifest.py     # rebuilds manifest.json
cd cli && ./install.sh               # updates installed assets

Replacing an existing car's image

Use manual_override.py instead of add_car.py:

python scripts/manual_override.py \
  bugatti_chiron ~/Downloads/new_chiron.jpg \
  --source-url "https://commons.wikimedia.org/wiki/File:new_chiron.jpg" \
  --license "CC BY-SA 4.0" \
  --author "New Photographer"

The script backs up the old files with a _replaced suffix and validates the new image.

Contributing common-name aliases

The alias map in cli/internal/cmd/aliases.go maps casual names ("chiron", "rolls royce ghost", "F40") to canonical slugs. Add a new entry, rebuild with cd cli && go build ., then PR.

Uninstalling

cd path/to/hypercar-colorscripts/cli
./uninstall.sh

Prompts:

Uninstall only hypercar-colorscripts (option 1, default)
Uninstall both hypercar-colorscripts and pokemon-colorscripts (option 2)

Removes: the binary, ~/.local/share/hypercar-colorscripts/, ~/.config/hypercar-colorscripts/, our marker-bracketed blocks in rc files.

Restores: any pokemon-colorscripts startup line that install.sh commented out.

Preserves: your PATH exports, every other line in your rc files, everything under ~/.config/ that isn't ours, timestamped backups of your rc files.

Troubleshooting

Always start with:

hypercar-colorscripts --doctor

Common issues:

Nothing appears when I open a new terminal

Check that the block was added to your rc file:

grep -n "hypercar-colorscripts" ~/.zshrc ~/.bashrc 2>/dev/null

Should show marker lines. If empty, re-run ./install.sh and answer Y at the "Proceed?" prompt.

Verify the binary is on your PATH:

which hypercar-colorscripts

I see ANSI text but I expected a real image

Your terminal probably doesn't support the Kitty graphics protocol. Run --doctor — the "image protocol" line will say what it detected. Try Kitty, Ghostty, WezTerm, or iTerm2 (macOS).

Install script wrote to .bashrc but I use zsh

Happens if you ran ./install.sh from VS Code's integrated bash terminal. Fixed in the current version by detecting the login shell via getent passwd $USER. Uninstall + reinstall from your regular terminal.

Vintage install fails saying "must run from cloned repo"

install-vintage.sh needs the source assets. If you deleted the clone, re-clone it and run install-vintage.sh from that fresh clone.

Still stuck? Open an issue with the full output of hypercar-colorscripts --doctor.

Project structure

hypercar-colorscripts/
├── README.md                    ← you are here
├── LICENSE                      ← GPLv3 (code license)
├── NOTICE                       ← attribution requirements
├── ASSETS-LICENSING.md               ← code-vs-asset licensing explanation
├── CREDITS.md                   ← per-image attribution summary
├── manifest.json                ← 690 cars, generated by build_manifest.py
│
├── assets/
│   ├── images/                  ← 512×256 PNGs, one per car
│   ├── ansi/                    ← pre-rendered ANSI text art
│   └── licenses/                ← per-car JSON attribution files
│
├── cli/                         ← the Go binary + install scripts
│   ├── install.sh
│   ├── uninstall.sh
│   ├── install-vintage.sh
│   ├── uninstall-vintage.sh
│   ├── _vintage_helper.py       ← shared logic for vintage scripts
│   ├── Makefile
│   ├── go.mod / go.sum
│   ├── main.go
│   └── internal/
│       ├── cmd/                 ← cobra commands + matcher + doctor
│       ├── config/              ← config.json parsing
│       ├── manifest/            ← manifest.json parsing
│       ├── pokemon/             ← pokemon-colorscripts integration
│       ├── renderer/            ← chafa invocation
│       └── terminal/            ← terminal detection
│
├── data/
│   ├── car_database_v2.txt      ← human-editable source of truth
│   ├── pilot_cars.txt           ← which cars to fetch
│   └── aliases_source.md        ← notes for the alias map
│
├── scripts/                     ← Python pipeline (20 scripts)
│   ├── add_car.py               ← contributor: add new cars
│   ├── manual_override.py       ← contributor: replace existing images
│   ├── build_manifest.py
│   ├── audit_licenses.py
│   ├── generate_ansi.py
│   ├── generate_png.py
│   ├── remove_backgrounds.py    ← rembg wrapper
│   └── ...
│
└── .github/workflows/
    └── ci.yml                   ← go build + python + shellcheck

Credits

Every image in this project is redistributable under its own free license. Full attribution for each car is in assets/licenses/<slug>.json and summarized in CREDITS.md. Wikimedia Commons and its contributors deserve most of the credit — this project is a curation on top of their work.

The project itself draws inspiration from pokemon-colorscripts by phoneybadger — the concept of "art in your terminal on every session" is theirs. This is a spiritual sibling for the automotive-adjacent crowd.

Terminal image rendering uses chafa by Hans Petter Jansson. System info alongside images uses fastfetch. Background removal in the contributor pipeline uses rembg.

Related projects

pokemon-colorscripts — the direct inspiration
fastfetch — system info alongside logos
chafa — universal terminal image rendering
pipes.sh — another terminal-beauty classic

License

The code in this repository is licensed under the GNU General Public License, version 3 or later (GPLv3+), with additional attribution requirements under GPLv3 §7(b) recorded in NOTICE. See LICENSE for the full text.

The images under assets/images/ (and their pre-rendered ANSI counterparts under assets/ansi/) are each licensed individually under a free-culture license — CC0, CC BY, CC BY-SA, GFDL, Public Domain, Free Art, or Copyrighted Free Use. Per-image attribution is in assets/licenses/<slug>.json and summarized in CREDITS.md. See ASSETS-LICENSING.md for the full explanation.

In short:

✅ Use, modify, redistribute, or fork the code — freely, personally or commercially
✅ Contribute back — issues, PRs, new cars, aliases, translations — all warmly welcomed
🙏 If you fork or build on this work, please preserve the NOTICE file — as one of the first projects to bring curated car art to terminal startup, we'd like the origin to travel with derivatives
📸 If you redistribute the images, keep assets/licenses/ intact so each photographer gets proper credit
🔀 Modified versions should be clearly labeled as forks (rename, or note in your README) — this is a friendly request, not a legal blocker

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github/workflows		.github/workflows
assets		assets
cli		cli
data		data
docs		docs
scripts		scripts
.gitignore		.gitignore
ASSETS-LICENSING.md		ASSETS-LICENSING.md
CREDITS.md		CREDITS.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
manifest.json		manifest.json

Folders and files

Latest commit

History

Repository files navigation

hypercar-colorscripts

What is this?

Features

Preview

Prerequisites

Quick install

Usage

Random car (the default)

Named car — smart lookup

Filter and roll

Discovery

Info and attribution

Toggle rendering mode

Toggle pokemon mixing

Health check

Complete command reference

Vintage cars

From the installed binary

From the source repo

Terminal support

Shell integration

Configuration

Contributing

Adding a new car

Replacing an existing car's image

Contributing common-name aliases

Uninstalling

Troubleshooting

Project structure

Credits

Related projects

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages