zigdex

A fast, lightweight Pokemon sprite viewer for your terminal written in Zig.

Features

🎲 Random Pokemon with 1/128 shiny chance
✨ Shiny variant support
🚀 Sprites embedded in binary (works offline)
📦 Single self-contained executable
⚡ Optimized for shell startup scripts

Performance

| Command | Mean [µs] | Min [µs] | Max [µs] | Relative | |:---|---:|---:|---:|---:| | zigdex random | 630.4 ± 130.2 | 407.6 | 1993.0 | 1.00 | | pokeget random | 1203.0 ± 387.7 | 889.1 | 10657.3 | 1.91 ± 0.73 | | krabby random | 3632.3 ± 284.5 | 3182.5 | 5362.4 | 5.76 ± 1.27 |

zigdex   ▓░░░░░░░░░  0.63ms  ← 5.8x faster than krabby
pokeget  ▓▓░░░░░░░░  1.20ms
krabby   ▓▓▓▓▓▓▓▓░░  3.63ms

<sub>Benchmarked with hyperfine --warmup 3</sub>

Installation

Homebrew (macOS/Linux)

brew tap Decryptu/tap
brew install zigdex

Note: While zigdex is being reviewed for inclusion in Homebrew core, you can install it from my personal tap.

Manual Installation

Download the appropriate binary for your architecture from the releases page and add it to your PATH.

Building

zig build

This will:

Generate embedded sprites from your assets/ directory at compile time
Create a single executable at zig-out/bin/zigdex
Embed all 1010+ Pokemon sprites directly into the binary

Usage

# Random Pokemon (1/128 chance for shiny)
zigdex random
zigdex --random

# Specific Pokemon by name
zigdex pikachu
zigdex bulbasaur charmander squirtle

# By Pokedex number
zigdex 25
zigdex 1 4 7

# Force shiny variant
zigdex pikachu --shiny
zigdex random --shiny

# Hide Pokemon name
zigdex pikachu --hide-name
zigdex random --hide-name

Shell Integration

Add to your .zshrc or .bashrc:

# Show random Pokemon on terminal start
zigdex --random --hide-name

# Or with fastfetch
alias fastfetch='zigdex --random --hide-name | command fastfetch --logo-type file-raw --logo -'

Note: fastfetch is a fast system information tool similar to neofetch.

Project Structure

zigdex/
├── src/
│   ├── main.zig       # Entry point and CLI
│   ├── args.zig       # Argument parser
│   └── sprites.zig    # Pokemon lookup and display
├── tools/
│   └── generate_sprites.zig  # Build-time sprite embedder
├── assets/
│   ├── pokemon.json
│   └── colorscripts/
│       ├── regular/   # Normal sprites
│       └── shiny/     # Shiny variants
└── build.zig

Implementation Details

Compile-Time Sprite Embedding

Sprites are converted to byte arrays at compile time
The generate_sprites.zig tool runs during build
Creates embedded_sprites.zig with all Pokemon data
No runtime filesystem dependencies
Binary size: ~1.8MB (fully self-contained; sprites zlib-compressed)

Fast Random Selection

Uses std.Random.DefaultPrng with nanosecond seed
1/128 chance for shiny (mimicking main series games)
O(1) lookup by index
Zero filesystem I/O at runtime

Pokemon Lookup

Supports multiple lookup methods:

Case-insensitive name matching (pikachu, PIKACHU)
Slug matching (charizard-mega-x)
Pokedex number (25, 150)

Memory Management

Uses GeneralPurposeAllocator for safety
Proper defer patterns for cleanup
No memory leaks in debug builds
Efficient argument parsing

Command-Line Options

| Option | Short | Description | |--------|-------|-------------| | --random | -r | Display random Pokemon (1/128 shiny) | | --shiny | -s | Force shiny variant | | --hide-name | | Don't print Pokemon name | | --help | -h | Show help message |

Requirements

Zig 0.15.2 or later
Terminal with ANSI color support
Pokemon sprite assets in assets/ directory

Recommended Terminals

For the best experience, we recommend using:

iTerm2 - Works great with zigdex
Ghostty - Works great with zigdex

Both terminals provide excellent ANSI color support and render Pokemon sprites beautifully.

License

MIT

Zigdex

Install / Use

README