🔮 Ghostforge

A complete, opinionated macOS terminal configuration built around Ghostty — the GPU-accelerated terminal emulator. This repo includes everything you need to transform your terminal into a fast, beautiful, keyboard-centric workspace.

---

✨ Features

Category	What You Get
🎨 Appearance	Catppuccin Mocha/Latte auto-theme, glassmorphism (blur + opacity), dimmed unfocused panes
⌨️ Keyboard	Vim-style split navigation (Alt+HJKL), zoom toggle, tab management
🚀 Prompt	Starship with git metrics, battery, node/python version, command timer
📂 Navigation	Zoxide smart cd + fzf fuzzy finder
🛠️ Modern Tools	eza → ls, bat → cat, fd → find, rg → grep, dust → du, btop → top
📁 File Manager	Yazi terminal file manager with directory persistence
🔀 Git	lazygit TUI + delta syntax-highlighted diffs

---

🚀 Quick Install

Prerequisites: Homebrew must be installed.

# Clone the repo
git clone https://github.com/KevinArce/ghostforge.git
cd ghostforge

# Run the installer
chmod +x install.sh
./install.sh

That's it. Open Ghostty and you're ready to go.

Note

The installer will backup your existing .zshrc before overwriting it. The backup is saved as ~/.zshrc.backup.<timestamp>.

---

📦 What Gets Installed

Terminal & Font

Package	Type	Description
ghostty	Cask	GPU-accelerated terminal emulator
font-jetbrains-mono-nerd-font	Cask	JetBrains Mono with Nerd Font icons

Shell Enhancements

Package	Description
starship	Cross-shell prompt with git/language integration
zoxide	Smarter cd that learns your habits
fzf	Fuzzy finder for files, history, and directories
zsh-autosuggestions	Fish-like inline history suggestions
zsh-syntax-highlighting	Real-time command syntax coloring

Modern Unix Replacements

Package	Replaces	Why
bat	cat	Syntax highlighting, line numbers
eza	ls	Icons, git status, tree view
fd	find	5x faster, simpler syntax
ripgrep	grep	10x faster, respects .gitignore
dust	du	Visual disk usage bars
btop	top	Beautiful system monitor
yazi	ranger	Blazing fast file manager
lazygit	git	Full git TUI
git-delta	diff	Syntax-highlighted git diffs
tmux	—	Terminal multiplexer

---

📁 Repository Structure

ghostforge/
├── README.md            # You are here
├── install.sh           # One-command setup script
├── docs/
│   └── USER_GUIDE.md    # Full tutorial with shortcuts & commands
└── configs/
    ├── ghostty_config   # → ~/.config/ghostty/config
    ├── starship.toml    # → ~/.config/starship.toml
    └── .zshrc           # → ~/.zshrc

---

⌨️ Key Shortcuts (Cheat Sheet)

Ghostty Window Management

Shortcut	Action
Cmd+T	New tab
Cmd+W	Close surface
Cmd+Shift+[ / ]	Previous / Next tab
Ctrl+Shift+D	Split ↓
Ctrl+Shift+→	Split →
Ctrl+Shift+W	Close split
Alt+H/J/K/L	Navigate splits (vim)
Alt+Z	Zoom / Unzoom pane

Shell Navigation

Shortcut / Command	Action
z <query>	Smart jump to directory
cdi	Interactive fuzzy directory picker
Ctrl+R	Fuzzy search history
Ctrl+T	Fuzzy find file
Alt+C	Fuzzy cd into directory
y	Open Yazi file manager
lg	Open lazygit

Aliases

Alias	Runs
ls	eza --icons
ll	eza -lh --git --icons
la	eza -lha --git --icons
cat	bat --style=plain
grep	rg
find	fd
du	dust
top	btop

---

🎨 Customization

All config files live in configs/ — edit them, re-run install.sh, and you're updated.

What	File	Docs
Terminal appearance & keybinds	configs/ghostty_config	Ghostty Config Reference
Prompt modules & colors	configs/starship.toml	Starship Configuration
Aliases, plugins & shell init	configs/.zshrc	—

Quick Tweaks

# Ghostty: adjust transparency (configs/ghostty_config)
background-opacity = 0.85   # 0.0 (transparent) → 1.0 (opaque)
background-blur = 30        # Higher = more frosted glass

# Ghostty: change font size
font-size = 14

---

📖 Full Documentation

See the User Guide for:

• Detailed walkthrough of every tool
• All keybindings and shortcuts
• Git workflow tips
• Yazi navigation reference
• Known issues and workarounds

---

🔄 Updating

# Pull latest changes
git pull

# Re-run installer (it's idempotent)
./install.sh

---

⚠️ Notes

• macOS only — designed for macOS with Apple Silicon (Homebrew at /opt/homebrew)
• NVM compatible — the .zshrc includes NVM initialization (edit if you use a different Node manager)
• cd is aliased to z — use builtin cd if you need the original behavior
• find/grep are aliased — use /usr/bin/find or /usr/bin/grep for the originals

---

📄 License

MIT — do whatever you want with it.