GhosttyFetch

An animated system information display tool for the Ghostty terminal emulator. Perfect for terminal enthusiasts and the ricing community who want to showcase their terminal setup while maintaining functionality.

Overview

GhosttyFetch combines visual appeal with practical utility, displaying an animated Ghostty logo alongside real-time system information. Designed specifically for the terminal ricing community, it provides an eye-catching splash screen that's also a functional system monitoring tool and command launcher.

Key Features:

• 235-frame smooth ASCII art animation
• Real-time system information display via fastfetch
• Highly customizable colors and gradients
• Interactive command prompt with live input
• Built in Zig for performance and efficiency
• Perfect for terminal startup scripts

Demo

What It Does

GhosttyFetch creates an engaging terminal experience by:

1. Loading configuration from config.json and environment variables (FPS, colors, gradient settings, system info modules)
2. Executing fastfetch to gather system information in JSON format
3. Loading animation.json containing 235 frames of ASCII art with color markup
4. Rendering the animation with:
   • Custom brand colors for highlighted elements
   • Vertical gradient effects for the ASCII art
   • Optional scrolling gradient animation
5. Displaying a formatted system information panel with bordered layout
6. Enabling non-blocking keyboard input while the animation plays
7. Showing a live command prompt at the bottom
8. Executing your command when you press Enter
9. Exiting with your command's exit code

It's ideal for adding visual flair to your terminal while providing quick access to system information and seamless command execution.

Requirements

Before installation, ensure you have:

• Operating System: macOS or Linux (POSIX-compliant systems)
• Zig: Version 0.15.2 or compatible
• fastfetch: Required for system information display

  # macOS
  brew install fastfetch
  
  # Arch Linux
  pacman -S fastfetch
  
  # Ubuntu/Debian
  apt install fastfetch

Installation

Quick Start

# Clone the repository
git clone https://github.com/BarutSRB/GhosttyFetch.git
cd GhosttyFetch

# Build the application
zig build-exe ghosttyfetch.zig

# For optimized build
zig build-exe -O ReleaseFast ghosttyfetch.zig

# Run (must be in directory with config.json and animation.json)
./ghosttyfetch

File Structure

The executable requires these files in the same directory:

GhosttyFetch/
├── ghosttyfetch          # Compiled binary
├── config.json           # Configuration (required)
└── animation.json        # Animation frames (required)

Configuration

config.json Settings

All configuration is managed through config.json, with environment variable overrides available.

Display Settings

{
  "fps": 30.0,
  "color": "#3551f3",
  "force_color": false,
  "no_color": false
}

Options:

• fps (float): Animation frame rate. Range: 1.0-120.0. Default: 20.0
• color (string): Brand color for highlighted elements
  • Hex format: #rrggbb or rrggbb
  • ANSI format: 38;5;n or 38;2;r;g;b
  • Disable: "off", "0", "false", "none"
• force_color (boolean): Force color output even when not detected as TTY
• no_color (boolean): Disable all color output

Gradient Settings

{
  "white_gradient_colors": [
    "#d7ff9e", "#c3f364", "#f2e85e", "#f5c95c",
    "#f17f5b", "#f45c82", "#de6fd2", "#b07cf4",
    "#8b8cf8", "#74a4ff", "#78b8ff"
  ],
  "white_gradient_scroll": true,
  "white_gradient_scroll_speed": 20.0
}

Options:

• white_gradient_colors (array): Colors applied top-to-bottom to non-branded ASCII art. Empty array disables gradient.
• white_gradient_scroll (boolean): Enable animated gradient scrolling
• white_gradient_scroll_speed (float): Scroll speed in lines per second

Fastfetch Configuration

{
  "fastfetch": {
    "enabled": true,
    "command": "fastfetch",
    "modules": [
      "OS", "Host", "Kernel", "CPU", "GPU",
      "Memory", "Disk", "LocalIp"
    ],
    "list_available": false
  }
}

Options:

• enabled (boolean): Enable/disable system information panel
• command (string): Fastfetch executable path or name
• modules (array): List of fastfetch modules to display
  • Available: Title, OS, Host, Kernel, Uptime, Packages, Shell, Display, Terminal, TerminalFont, WM, WMTheme, Cursor, CPU, GPU, Memory, Swap, Disk, LocalIp
• list_available (boolean): Print available modules to stderr for reference

Environment Variables

Environment variables override config.json settings:

# Override FPS
GHOSTTY_FPS=60 ./ghosttyfetch

# Override color
GHOSTTY_COLOR=#ff0066 ./ghosttyfetch

# Force color output
FORCE_COLOR=1 ./ghosttyfetch

# Disable colors
NO_COLOR=1 ./ghosttyfetch

Available Variables:

• GHOSTTY_FPS: Override frame rate
• GHOSTTY_COLOR: Override brand color
• FORCE_COLOR: Force color output
• NO_COLOR: Disable all colors
• SHELL: Shell for command execution
• PS1: Custom prompt format (supports \u, \h, \w, $)

Usage

Running the Application

# Basic execution
./ghosttyfetch

# With environment overrides
GHOSTTY_FPS=60 GHOSTTY_COLOR=#ff0066 ./ghosttyfetch

What to Expect

When you run GhosttyFetch, you'll see:

1. Animation (left): 235 frames of Ghostty logo animation cycling continuously
2. System Info (right): Bordered panel showing your selected system information
3. Command Prompt (bottom): Interactive prompt where you can type commands

Interacting with the Prompt

• Type: Any regular characters (letters, numbers, symbols)
• Backspace/Delete: Remove the last character
• Enter: Execute your command and exit the application

The application exits with your command's exit code, making it suitable for shell integration.

Integration with Shell Startup

Add to your ~/.zshrc or ~/.bashrc:

# Run GhosttyFetch on terminal startup
if [[ $- == *i* ]]; then
  /path/to/ghosttyfetch
fi

Customization Examples

# High frame rate for smooth animation
GHOSTTY_FPS=90 ./ghosttyfetch

# Custom color theme
GHOSTTY_COLOR=#ff0066 ./ghosttyfetch

# Minimal system info (edit config.json)
{
  "fastfetch": {
    "modules": ["OS", "Kernel", "CPU", "Memory"]
  }
}

Popular Color Themes

Here are some community-favorite color schemes:

Dracula:

{
  "color": "#bd93f9",
  "white_gradient_colors": ["#8be9fd", "#50fa7b", "#f1fa8c", "#ffb86c", "#ff79c6", "#bd93f9"]
}

Nord:

{
  "color": "#88c0d0",
  "white_gradient_colors": ["#8fbcbb", "#88c0d0", "#81a1c1", "#5e81ac"]
}

Gruvbox:

{
  "color": "#fe8019",
  "white_gradient_colors": ["#b8bb26", "#fabd2f", "#fe8019", "#fb4934", "#d3869b", "#83a598"]
}

Tokyo Night:

{
  "color": "#7aa2f7",
  "white_gradient_colors": ["#9ece6a", "#0db9d7", "#7aa2f7", "#bb9af7"]
}

Troubleshooting

Common Issues

"fastfetch: command not found"

• Install fastfetch via your package manager
• Verify installation: which fastfetch
• Alternative: Set full path in config.json: "command": "/usr/local/bin/fastfetch"

"Failed to load config.json"

• Ensure the file exists in the working directory
• Validate JSON syntax: jq . config.json
• Check file permissions: chmod 644 config.json

Colors not displaying

• Check NO_COLOR environment variable: env | grep NO_COLOR
• Set force_color: true in config.json
• Verify terminal supports ANSI colors: echo -e "\x1b[31mRED\x1b[0m"

Animation issues

• Verify animation.json exists and is readable
• Check file size (expected: ~476KB)
• Try adjusting FPS value in config

Command execution fails

• Verify SHELL environment variable: echo $SHELL
• Ensure shell is executable: ls -l $SHELL
• Test shell manually: $SHELL -c "echo test"

Contributing

Contributions are welcome! We appreciate bug fixes, new features, documentation improvements, and creative enhancements.

Priority: High-Resolution Animation Support

The current animation.json is a downsampled version. A high-resolution original exists at:

contribute/original_animation.json

Challenge: Implement dynamic terminal size detection and adaptive frame scaling to utilize the high-resolution animation without quality loss.

Areas of Interest:

• ASCII art scaling algorithms
• Dynamic terminal dimension detection
• Frame interpolation or adaptive rendering
• Performance optimization for real-time display
• Better looking ANSI system information

This is the maintainer's top priority for contributions. If you have experience in these areas, your help would be greatly appreciated!

How to Contribute

1. Fork the repository: https://github.com/BarutSRB/GhosttyFetch
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Test thoroughly: zig build-exe ghosttyfetch.zig && ./ghosttyfetch
5. Submit a pull request with a clear description

Contribution Ideas:

• Additional color themes and presets
• Animation effects and transitions
• Layout customization options
• Performance improvements
• Documentation enhancements
• Bug fixes and quality of life improvements

Technical Details

Built With:

• Language: Zig 0.15.2
• Dependencies: Zig standard library only
• Runtime Requirement: fastfetch

Key Features:

• Non-blocking terminal I/O for smooth animation
• Raw terminal mode for keystroke capture
• ANSI escape code rendering for colors and positioning
• JSON parsing for configuration and animation data
• Child process spawning for fastfetch integration
• Smart text wrapping and alignment

Animation Format:

• 235 frames, 21 lines per frame
• HTML-style <span class="b"> markup for brand colors
• Vertical gradient application to unmarked text
• Optional scrolling gradient effect

License

MIT License

Copyright (c) 2024 BarutSRB

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgments

• Animation sourced from ghostty.org
• Built for the Ghostty terminal emulator by Mitchell Hashimoto
• System information provided by fastfetch
• Created for the terminal ricing and customization community

Support

• Issues & Bug Reports: https://github.com/BarutSRB/GhosttyFetch/issues
• Discussions & Questions: https://github.com/BarutSRB/GhosttyFetch/discussions
• Documentation: This README and inline code comments

---

Enjoy customizing your terminal experience with GhosttyFetch!