Pokémon Fastfetch

A fast, offline Pokémon dashboard for Kitty terminals, built with Bash.

About

Pokémon Fastfetch replaces a traditional terminal startup screen with a Pokémon panel and a two-column system-information dashboard.

It combines:

a locally cached Pokédex;
local Pokémon artwork;
ImageMagick rendering;
Kitty's graphics protocol;
Bash-based system detection;
Fish shell integration.

After installation, normal usage does not require an internet connection. Rendered Pokémon panels are cached and reused until their source data, image, dimensions, or renderer version changes.

Highlights

Random Pokémon whenever a Kitty terminal opens
Select Pokémon by name or National Pokédex number
Fixed-Pokémon and random modes
Offline Pokédex data
Cached PNG rendering
Base stats, abilities, types, region, generation, height, weight, and category
System information panel
Configurable panel dimensions and visibility
XDG-compatible installation paths
Fish shell integration
Safe reinstall and migration workflow
Backups of previous installations
Shared Bash utility library
Automated tests
ShellCheck validation
GitHub Actions continuous integration

Preview

The upper panel contains Pokémon information:

sprite;
name and Pokédex number;
primary and secondary types;
HP, Attack, Defense, Special Attack, Special Defense, and Speed;
total base stats;
abilities;
region and generation;
category;
height and weight.

The lower section contains system information such as:

operating system and kernel;
uptime and package count;
shell, terminal, window manager, and display;
CPU, GPU, memory, disk, and network;
machine model, installation age, and font.

Requirements

Runtime

Linux
Bash
Kitty and kitten
jq
ImageMagick (magick)
fontconfig and fc-match
JetBrains Mono Nerd Font
a local Pokémon image collection, such as pokimg

The main scripts also use standard Linux utilities including awk, sed, find, shuf, tput, df, uname, hostname, stat, date, and tr.

Optional integrations

Fish shell, for the generated fastfetch function and terminal autostart
Hyprland tools, for richer display and window-manager detection
xrandr, as a display-detection fallback
lspci and lscpu, for hardware details
ip, for network information
pacman or Flatpak, for package counts

Arch Linux / CachyOS

Install the main packages with:

sudo pacman -S --needed \
  bash \
  fish \
  kitty \
  jq \
  imagemagick \
  fontconfig \
  pciutils \
  iproute2

Install ShellCheck for development:

sudo pacman -S --needed shellcheck

A Nerd Font package may also be required depending on your system configuration.

Installation

Clone the repository:

git clone https://github.com/But0o/pokemon-fastfetch.git
cd pokemon-fastfetch

Run the installer:

chmod +x install.sh
./install.sh

The installer:

validates the required project files;
validates Bash syntax and the bundled Pokédex;
checks runtime dependencies;
detects the Pokémon image directory;
backs up an existing installation when needed;
installs the scripts and shared library;
writes or updates the user configuration;
copies the bundled Pokédex into the cache;
generates Fish integration;
validates the installed files.

Non-interactive installation

./install.sh --yes

Disable terminal autostart

./install.sh --no-autostart

Specify the image directory

./install.sh --pokemon-dir "$HOME/.local/share/pokimg/images"

Alternative example:

./install.sh --pokemon-dir "$HOME/pokimg/images"

Installer options

Option	Description
`--yes`, `-y`	Accept installer confirmations automatically
`--no-autostart`	Do not launch Pokémon Fastfetch automatically in new Kitty sessions
`--pokemon-dir PATH`	Use a specific Pokémon image directory
`--help`, `-h`	Show installer help

Usage

The installer creates a Fish function named fastfetch that forwards arguments to Pokémon Fastfetch.

Random Pokémon

fastfetch

Pokémon by name

fastfetch pikachu
fastfetch charizard
fastfetch rayquaza

Pokémon by Pokédex number

fastfetch 25
fastfetch 6
fastfetch 384

Random Pokémon for one execution

fastfetch --random

The alias below is also accepted:

fastfetch random

Force a new render

fastfetch --rerender pikachu

This removes cached panels matching the request before rendering again.

Help

fastfetch --help

You may also call the installed script directly:

~/.local/share/pokemon-fastfetch/random-fastfetch.sh pikachu

Fixed Pokémon mode

Choose a Pokémon that should appear whenever a new terminal opens:

fastfetch --set gengar

A number also works:

fastfetch --set 94

Return to automatic random selection:

fastfetch --random-mode

The fixed selection is stored at:

~/.config/pokemon-fastfetch/fixed-pokemon

Configuration

The installer creates:

~/.config/pokemon-fastfetch/config

The file is sourced by the Bash scripts, so values use shell-assignment syntax.

Example:

# Pokémon Fastfetch
# File managed by install.sh

# Paths
POKEMON_DIR=/home/user/.local/share/pokimg/images
CACHE_DIR=/home/user/.cache/pokemon-fastfetch
INSTALL_DIR=/home/user/.local/share/pokemon-fastfetch

# Pokémon panel
POKEMON_PANEL_WIDTH=1580
POKEMON_PANEL_HEIGHT=470
POKEMON_PANEL_ROWS=22

# System panel
SYSTEM_PANEL_MAX_WIDTH=150
COLUMN_GAP=6

# Visual options
SHOW_SYSTEM_INFO=true
SHOW_COLOR_PALETTE=true

Visual settings

Variable	Default	Purpose
`POKEMON_PANEL_WIDTH`	`1580`	Width of the rendered Pokémon PNG
`POKEMON_PANEL_HEIGHT`	`470`	Height of the rendered Pokémon PNG
`POKEMON_PANEL_ROWS`	`22`	Number of terminal rows reserved for the Kitty image
`SYSTEM_PANEL_MAX_WIDTH`	`150`	Maximum width of the lower system panel
`COLUMN_GAP`	`6`	Spacing between system-information columns
`SHOW_SYSTEM_INFO`	`true`	Show or hide the system-information section
`SHOW_COLOR_PALETTE`	`true`	Show or hide the terminal color dots

Example: show only the Pokémon panel:

SHOW_SYSTEM_INFO=false

Example: hide only the color palette:

SHOW_COLOR_PALETTE=false

During a reinstall or upgrade, the installer updates managed paths while preserving known visual preferences.

XDG paths

Pokémon Fastfetch follows XDG base-directory variables when they are defined.

Purpose	Default path
Installation	`~/.local/share/pokemon-fastfetch`
Configuration	`~/.config/pokemon-fastfetch`
Cache	`~/.cache/pokemon-fastfetch`
Backups	`~/.local/share/pokemon-fastfetch-backups`
Fish integration	`~/.config/fish/conf.d/pokemon-fastfetch.fish`

These defaults change automatically when XDG_DATA_HOME, XDG_CONFIG_HOME, or XDG_CACHE_HOME are set.

Cache and offline behavior

Pokédex

~/.cache/pokemon-fastfetch/pokedex.json

The installer copies the repository's bundled file:

config/pokedex.json

Normal Pokémon selection and rendering use this local cache.

Rendered panels

~/.cache/pokemon-fastfetch/panels-v2/

Each panel filename includes a hash derived from:

renderer version;
panel width and height;
Pokémon data;
source-image modification time.

This allows previously rendered panels to be reused safely.

Temporary rendering files

~/.cache/pokemon-fastfetch/render-temp/

Temporary SVG and PNG files for a successful render are removed after the final panel is generated.

Rebuilding enriched data

build-pokedex-cache.sh can enrich an existing cache using PokeAPI. Network access is used only during this maintenance operation, not during normal terminal startup.

~/.local/share/pokemon-fastfetch/build-pokedex-cache.sh

The cache builder:

validates the current JSON;
creates a timestamped backup;
reuses entries that already contain complete statistics and abilities;
retries failed API requests;
preserves existing entries when an API request fails;
writes the finished cache atomically;
verifies the final entry count.

Updating

Pull the latest repository changes:

cd ~/pokemon-fastfetch
git pull origin main

For a regular reinstall using the current architecture:

./install.sh

For migration from an older installation:

./upgrade-v1-to-v2.sh

Upgrade options

Option	Description
`--yes`, `-y`	Accept confirmations automatically
`--no-autostart`	Disable automatic startup
`--pokemon-dir PATH`	Specify the image directory
`--help`, `-h`	Show migration help

The migration process is designed to:

detect previous installations;
create backups;
preserve a valid legacy Pokédex;
remove obsolete Fish references;
delegate the final installation to the current installer.

Uninstallation

Remove the installed scripts, configuration, and Fish integration:

./uninstall.sh

Skip confirmation:

./uninstall.sh --yes

Also remove the cache:

./uninstall.sh --remove-cache

Also remove installation backups:

./uninstall.sh --remove-backups

Remove everything managed by the project:

./uninstall.sh \
  --yes \
  --remove-cache \
  --remove-backups

Uninstaller options

Option	Description
`--yes`, `-y`	Do not request confirmation
`--remove-cache`	Remove the Pokémon Fastfetch cache
`--remove-backups`	Remove installer and migration backups
`--help`, `-h`	Show uninstaller help

The cloned Git repository itself is not removed by the uninstaller.

Project structure

pokemon-fastfetch/
├── .github/
│   └── workflows/
│       └── ci.yml
├── config/
│   └── pokedex.json
├── docs/
│   └── preview.png
├── lib/
│   └── common.sh
├── tests/
│   └── run-tests.sh
├── .editorconfig
├── .gitignore
├── .shellcheckrc
├── build-pokedex-cache.sh
├── install.sh
├── random-fastfetch.sh
├── render-pokemon.sh
├── uninstall.sh
├── upgrade-v1-to-v2.sh
├── CHANGELOG.md
├── LICENSE
├── README.md
└── VERSION

Main components

File	Responsibility
`random-fastfetch.sh`	Selects a Pokémon, gathers system information, and draws the terminal dashboard
`render-pokemon.sh`	Resolves Pokémon data and creates or reuses the cached PNG panel
`build-pokedex-cache.sh`	Enriches the local Pokédex through PokeAPI
`install.sh`	Validates and installs the application
`upgrade-v1-to-v2.sh`	Migrates older installations into the current layout
`uninstall.sh`	Removes installed resources
`lib/common.sh`	Shared messages, dependency checks, and path/JSON validation
`tests/run-tests.sh`	Runs syntax, data, library, and isolated-installation tests
`config/pokedex.json`	Bundled offline Pokémon database

Architecture

User command / terminal startup
              │
              ▼
     random-fastfetch.sh
              │
      ┌───────┴────────┐
      │                │
      ▼                ▼
Local Pokédex     System detection
      │
      ▼
render-pokemon.sh
      │
      ├── Existing hash-matched panel ──► reuse
      │
      └── No cached panel
              │
              ▼
       SVG + sprite render
              │
              ▼
      Cached final PNG
              │
              ▼
       Kitty graphics output

Normal execution is local. The network is only relevant when explicitly rebuilding or enriching the Pokédex cache.

Development

Run the full test suite

POKEMON_DIR="$HOME/.local/share/pokimg/images" \
  ./tests/run-tests.sh

The suite uses a temporary home directory and does not modify the user's real installation.

It currently validates:

Bash syntax for project scripts;
required repository files;
Pokédex JSON validity;
non-empty Pokédex contents;
shared-library validation functions;
isolated installation;
installed files and entry count;
command help screens.

Run ShellCheck

shellcheck \
  install.sh \
  uninstall.sh \
  upgrade-v1-to-v2.sh \
  random-fastfetch.sh \
  render-pokemon.sh \
  build-pokedex-cache.sh \
  lib/common.sh \
  tests/run-tests.sh

Run Bash syntax checks

bash -n install.sh
bash -n uninstall.sh
bash -n upgrade-v1-to-v2.sh
bash -n random-fastfetch.sh
bash -n render-pokemon.sh
bash -n build-pokedex-cache.sh
bash -n lib/common.sh
bash -n tests/run-tests.sh

Validate the Pokédex manually

jq empty config/pokedex.json
jq 'length' config/pokedex.json

Continuous integration

The GitHub Actions workflow runs on pushes and pull requests targeting main.

The CI job performs:

Bash syntax validation;
ShellCheck;
Pokédex JSON validation;
the automated test suite.

A failed check prevents an unnoticed syntax, lint, data, or installation regression from being treated as a valid change.

Troubleshooting

The image directory is not detected

Specify it explicitly:

./install.sh --pokemon-dir "/absolute/path/to/images"

The directory must contain at least one supported image file. The installer searches for PNG, WebP, JPEG, and GIF files.

The Pokédex cache is missing

Run the installer again:

./install.sh --yes

The bundled config/pokedex.json should be copied into the configured cache directory.

The cache is invalid

Check it manually:

jq empty ~/.cache/pokemon-fastfetch/pokedex.json

Restore it by reinstalling, or use an installer-created backup when appropriate.

A Pokémon cannot be found

Try its canonical English API-style name or its Pokédex number:

fastfetch mr-mime
fastfetch 122

The renderer includes normalization for several punctuation-heavy Pokémon names.

A sprite cannot be found

Check the configured path:

grep '^POKEMON_DIR=' ~/.config/pokemon-fastfetch/config

Confirm that the referenced directory exists and contains the requested Pokémon image.

The panel appears outdated

Force a new render:

fastfetch --rerender pikachu

Kitty does not display the panel

Check the terminal:

printf '%s\n' "$TERM"

Expected value inside Kitty:

xterm-kitty

Check the graphics helper:

command -v kitten

The dashboard appears twice

Ensure Pokémon Fastfetch is not started from multiple Fish locations.

The installer-managed integration is:

~/.config/fish/conf.d/pokemon-fastfetch.fish

Remove old manual calls from:

~/.config/fish/config.fish

System information is hidden

Check:

grep '^SHOW_SYSTEM_INFO=' \
  ~/.config/pokemon-fastfetch/config

Set it to:

SHOW_SYSTEM_INFO=true

Colors or icons look incorrect

Confirm that a compatible Nerd Font is installed and selected in Kitty. The renderer searches for JetBrains Mono Nerd Font variants.

Security notes

The configuration file is sourced as Bash code. Only place trusted shell assignments in:

~/.config/pokemon-fastfetch/config

Do not copy untrusted commands into that file.

The project does not require elevated privileges for its own installation. System package installation is separate and may require sudo.

Compatibility

The project has been developed and tested primarily with:

CachyOS
Arch Linux
Kitty
Fish
Hyprland

Other Linux distributions may work when the required commands are available, but package names and optional system-information integrations may differ.

Roadmap

v2.1

hardened installer;
bundled Pokédex installation;
centralized user configuration;
preserved visual preferences;
shared Bash library;
consistent validation and error handling;
safer migration workflow;
centralized version source;
automated test suite;
ShellCheck-clean codebase;
GitHub Actions CI;
expanded documentation.

v2.2

Planned areas of work:

smarter and approximate Pokémon search;
richer local Pokémon metadata;
additional command-line filters;
visual themes;
compact layouts for narrow terminals;
improved cache-management commands.

Future

AUR packaging;
additional sprite providers or styles;
broader shell integration;
community-contributed themes and layouts.

Contributing

Issues and pull requests are welcome.

Before submitting a change:

keep the scope focused;
preserve Bash compatibility and XDG paths;
run bash -n on modified scripts;
run ShellCheck;
run tests/run-tests.sh;
update documentation when behavior changes.

For larger features, open an issue first so the design can be discussed before implementation.

License

Pokémon Fastfetch is released under the MIT License.

Pokémon names and related trademarks belong to their respective owners. This is an unofficial fan-made terminal project and is not affiliated with or endorsed by Nintendo, Game Freak, The Pokémon Company, or Creatures Inc.

Author

Developed by But0o.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
config		config
docs		docs
lib		lib
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.shellcheckrc		.shellcheckrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
add-missing-pokemon.sh		add-missing-pokemon.sh
build-pokedex-cache.sh		build-pokedex-cache.sh
install.sh		install.sh
random-fastfetch.sh		random-fastfetch.sh
render-pokemon.sh		render-pokemon.sh
uninstall.sh		uninstall.sh
upgrade-v1-to-v2.sh		upgrade-v1-to-v2.sh

Latest commit

History

Folders and files

Repository files navigation

Pokémon Fastfetch

About

Highlights

Preview

Requirements

Runtime

Optional integrations

Arch Linux / CachyOS

Installation

Non-interactive installation

Disable terminal autostart

Specify the image directory

Installer options

Usage

Random Pokémon

Pokémon by name

Pokémon by Pokédex number

Random Pokémon for one execution

Force a new render

Help

Fixed Pokémon mode

Configuration

Visual settings

XDG paths

Cache and offline behavior

Pokédex

Rendered panels

Temporary rendering files

Rebuilding enriched data

Updating

Upgrade options

Uninstallation

Uninstaller options

Project structure

Main components

Architecture

Development

Run the full test suite

Run ShellCheck

Run Bash syntax checks

Validate the Pokédex manually

Continuous integration

Troubleshooting

The image directory is not detected

The Pokédex cache is missing

The cache is invalid

A Pokémon cannot be found

A sprite cannot be found

The panel appears outdated

Kitty does not display the panel

The dashboard appears twice

System information is hidden

Colors or icons look incorrect

Security notes

Compatibility

Roadmap

v2.1

v2.2

Future

Contributing

License

Author

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages