zigdex

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

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

_{Benchmarked with hyperfine --warmup 3}

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:

1. Generate embedded sprites from your assets/ directory at compile time
2. Create a single executable at zig-out/bin/zigdex
3. 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: ~18MB (fully self-contained; ~1.3MB gzip 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

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