tok-speed

dotfiles

Opinionated, curated dotfiles for the discerning developer

A comprehensive cross-platform dotfiles repository that makes strong choices about your development environment. Supporting macOS, Linux (Ubuntu, Fedora, Arch), and WSL with both personal and work configurations, it's designed for developers who want a thoughtfully curated setup without the decision fatigue.

Features

• Opinionated tool selection - Carefully curated applications and configurations that work well together
• Cross-platform compatibility - Consistent experience across macOS, Ubuntu, Fedora, Arch Linux, and WSL
• Environment-aware setup - Thoughtfully separated configurations for personal and work environments
• Zero-decision installation - Smart system detection with guided setup—no overwhelming choices
• Modular architecture - Component-based system with sensible defaults
• Symlink-based configs - Centralized configuration management for easy updates
• AI development tools - Curated AI assistant rules for Cursor

[!TIP] The system automatically detects your platform and environment, making installation straightforward across different setups.

Quick Start

YOLO It

curl -fsSL https://jordangarcia.me/dotfiles/boot.sh | bash

This will automatically clone/update the repo, fetch latest changes, and run interactive setup.

Interactive Installation (Recommended)

git clone https://github.com/whoisjordangarcia/dotfiles.git
cd dotfiles
./bin/dot -i              # Interactive setup

Alternative Methods

./bin/dot --system mac --work         # Direct installation
./bin/dot --system linux_ubuntu --personal

Headless Server / Proxmox / LXC

For lightweight servers (no desktop, bash instead of zsh), use the standalone bootstrap — it installs git curl vim neovim tmux htop + Claude Code and symlinks the bash config. See server/README.md.

bash <(curl -fsSL https://raw.githubusercontent.com/whoisjordangarcia/dotfiles/main/server-init.sh)

---

Configuration Components

Shell & Terminal

Zsh (configs/zshrc/)

Modular Z shell configuration with organized .zshrc-modules/:

Module	Purpose
.zshrc.history	50k command history with smart duplicate filtering, ignores mundane commands
.zshrc.aliases	reload, vim→nvim, ls→eza, cat→bat, top→btop, git shortcuts
.zshrc.functions	encode64/decode64, compress/decompress, web2app launcher creator
.zshrc.plugins	Completions + plugins: zsh-syntax-highlighting, zsh-autosuggestions, nx-completion
.zshrc.envvars	EDITOR, pyenv, colored man pages via bat
.zshrc.vim-mode	Vi keybindings in shell
.zshrc.work	Work-specific environment config

Key Aliases:

• gcm - checkout main, gpo - pull origin, gpf - push --force-with-lease
• wt-auto, wt-list, wt-remove - git worktree management
• dotfiles - quick access to this repo

Tmux (configs/tmux/)

Terminal multiplexer with extensive customization:

• Prefix: Ctrl+a (changed from default Ctrl+b)
• Navigation: Vim-style with vim-tmux-navigator (Ctrl+h/j/k/l seamless pane switching)
• Session Management: tmux-resurrect + tmux-continuum for persistence
• UI: Elegant minimal statusline with git status, CPU, memory, battery

Custom Scripts (~/.tmux/scripts/):

Script	Function
pane_title.sh	Gradient-colored pane borders by command (Claude=purple, nvim=green, nx=orange)
session_picker.sh	Process-aware session selection with zoxide integration
cpu_usage.sh	CPU monitoring for statusline
memory_usage.sh	RAM usage display

Plugins via TPM:

• vim-tmux-navigator, tmux-yank, tmux-resurrect, tmux-continuum
• tmux-sessionx, tmux-floax, tmux-prefix-highlight, tmux-cpu, tmux-battery

Ghostty (configs/ghostty/)

Fast, GPU-accelerated terminal emulator:

• Font: GohuFont 14 Nerd Font, 16px
• Window: No decoration, blur radius 20px, transparent
• Behavior: Mouse hide while typing, block cursor, clipboard access enabled
• Integration: Shell integration for Zsh, xterm-256color with RGB

Starship (configs/starship/)

Minimal, fast shell prompt:

• Format: Directory → git worktree indicator (🎯) → git branch/status → character
• Git Status: Custom symbols for ahead (⇡), diverged (⇕), behind (⇣), conflicts, modifications
• Character: Success (❯ cyan), Error (✗ bold cyan)
• Performance: 200ms command timeout

---

Code Editors

Neovim (configs/nvim/)

LazyVim distribution with 27+ extras enabled:

AI & Coding:

• claudecode - Claude Code integration
• yanky - Enhanced clipboard manager

Languages:

• Docker, Git, JSON, Markdown, Prisma, Python, Tailwind CSS, TypeScript, YAML

Editor Enhancements:

• aerial - Code outline/symbols
• harpoon2 - Quick file navigation
• illuminate - Highlight word references
• mini-diff - Inline git diffs
• outline - Symbol explorer
• treesitter-context - Shows code context at top

Additional:

• DAP debugging with Neovim Lua support
• ESLint + Prettier formatting
• Integrated test runner
• Lazy loading for fast startup

LazyGit (configs/lazygit/)

Terminal Git UI with custom commands:

• c key: Create draft PR via gh pr create --web --draft
• n key: New branch with type menu (feature/fix/hotfix/chore/docs/refactor)
• Naming: jordan/{type}-{name}
• Theme: Catppuccin Mocha (coral borders, blue text, dark background)
• Features: Nerd Font icons, fuzzy filter, numstat display, commit signing

---

Window Managers

Rift (configs/rift/) - macOS

Tiling window manager with integrated SketchyBar:

• Navigation: Alt+j/k/l/; for focus, Alt+Shift to move windows
• Workspaces: Alt+1-0 for 10 workspaces
• Modes: Visual resize mode, accordion layouts (vertical/horizontal)
• Integration: Auto-hides dock and menu bar

SketchyBar Integration:

• Dynamic status bar with workspace info
• SbarLua for Lua scripting
• Theme switching capability
• Custom app font for icons

Hyprland (configs/hypr/) - Arch Linux

Modern Wayland compositor:

Config	Purpose
hyprland.conf	Main entry, sources modular configs
monitors.conf	Display setup for retina 2x (5K/6K)
input.conf	Keyboard (US), touchpad settings
looknfeel.conf	Window rounding (12px), gaps, dwindle layout

HyDE Integration: Uses HyDE distribution for theming and extended configs.

Desktop Theming (configs/gtk-3.0/, gtk-4.0/, kvantum/, qt6ct/) - Arch Linux

Linux apps use two different UI toolkits, each with their own theming stack. These configs lock in a readable dark theme and prevent HyDE's wallbash auto-theming from generating unreadable color combinations.

GTK apps (themed by gtk-3.0/settings.ini + gtk-4.0/settings.ini + gsettings):

App	What it is
Brave	Web browser
Firefox	Web browser
Ghostty	Terminal emulator
Spotify	Music
Lutris	Game launcher
Nautilus	GNOME file manager
Pavucontrol	Volume control
Waybar	Status bar
File picker dialogs	xdg-desktop-portal-gtk

Qt apps (themed by qt6ct/qt6ct.conf + kvantum/kvantum.kvconfig):

App	What it is
Dolphin	KDE file manager
Ark	Archive manager
Claude Desktop	AppImage
Steam	Uses Qt underneath

Current theme choices:

• GTK: Gruvbox-Retro (dark) with Gruvbox-Plus-Dark icons
• Qt style: Kvantum with KvGnomeDark engine
• Qt colors: darker.conf color scheme
• Cursor: catppuccin-mocha-green-cursors

[!NOTE] HyDE's wallbash system dynamically generates a Wallbash-Gtk theme from wallpaper colors and sets it via gsettings. The theming/linux setup script overrides this back to Gruvbox-Retro for consistent readability.

Waybar (configs/waybar/) - Wayland Status Bar

Customizable panel for Hyprland:

Modules:

• Left: Power menu, HyDE menu, clipboard, wallpaper switcher, theme selector, Spotify
• Center: Clock, idle inhibitor
• Right: Privacy, system tray, battery, backlight, network, audio, keybind hints

Styling:

• Dark bar with pill-shaped module groupings
• Nerd Font workspace icons
• Wallbash color integration from HyDE

---

File Management

Dolphin (configs/dolphin/) - KDE File Manager

Feature-rich file manager for Arch Linux:

View Settings:

• Details mode with 64px preview icons
• Split view enabled, hidden files visible
• Full path in address bar (editable)
• Expandable folders, filter bar, zoom slider

Service Menus (right-click actions):

• Git integration via dolphin-plugins
• Copy path via wl-clipboard (Wayland)
• Custom .desktop actions

---

AI Development

Claude Code (configs/claude/)

Claude Code IDE settings and configuration.

---

Additional Configs

Directory	Purpose
configs/ssh/	SSH config with global defaults + Include ~/.ssh/hosts.local for per-machine host aliases
configs/git/	.gitconfig.template, .gitignore_global, work.gitconfig
configs/bat/	Syntax highlighting for cat replacement
configs/brave/	Browser customization
configs/codex/	Codex AI integration
configs/opencode/	OpenCode settings
configs/fastfetch/	System info display
configs/pyright/	Python type checking
configs/i3/	i3 window manager (Fedora)
configs/sway/	Sway compositor
configs/glazeWM/	GlazeWM (Windows)
configs/man/	Custom man pages for dotfiles

---

Platform Profiles

macOS (mac)

./bin/dot --system mac

Installs: Homebrew + macOS defaults, 1Password, Git/SSH/GitHub CLI, Zsh, Neovim, Node, Tmux, Starship, Rift (tiling WM) + Ghostty, cmux, LazyGit, Claude/Codex/OpenCode + Agents, Fastfetch, Brave, Sunshine

Work variant (--work): Same installer, same component list — script/mac_components.sh is the single source of truth. WORK_ENV=1 only changes environment-specific config (work git email, etc.), not which components install.

Arch Linux (linux_arch)

./bin/dot --system linux_arch

Installs: Pacman packages, Git/SSH/GitHub CLI, Node, LazyGit, Zsh, Vim, Tmux, Bat, Ghostty, Fonts, Starship, Fastfetch, Brave, Podman, Claude/Codex + Agents, Dolphin, HyDE theming (Hyprland/Rofi/Btop), VPN split-tunnel, UFW

Pacman packages: zsh, starship, tmux, ripgrep, eza, zoxide, wl-clipboard, fzf, jq, bat, dysk, htop, btop, ttf-jetbrains-mono-nerd, mangohud, darktable, podman, yubikey-manager, github-cli

Ubuntu (linux_ubuntu)

./bin/dot --system linux_ubuntu

Installs: Core dev tools via apt, Git/SSH, Zsh, Vim, Tmux, Node, LazyGit, Starship, Fastfetch, Brave

Fedora (linux_fedora)

./bin/dot --system linux_fedora

Installs: Git/Zsh/Vim/Tmux, i3wm, Polybar, LazyGit, Fonts, Starship, Fastfetch, Brave

Headless Server / Proxmox / LXC (server/)

Standalone, bash-based — not part of the bin/dot flow. No desktop, no zsh.

bash <(curl -fsSL https://raw.githubusercontent.com/whoisjordangarcia/dotfiles/main/server-init.sh)

Installs: git, curl, vim, neovim, tmux, htop (apt) + Claude Code (native installer). Symlinks bashrc, bash_profile, aliases, tmux.conf, plus the shared functions/ and gitconfig. Details + how to extend: server/README.md.

---

Architecture

dotfiles/
├── bin/
│   └── dot                    # Shell management CLI
├── boot.sh                    # Remote bootstrap script
├── server-init.sh             # Headless server one-liner bootstrap
├── server/                    # Bash config for servers/Proxmox/LXC (see server/README.md)
├── script/
│   ├── common/
│   │   ├── log.sh            # Logging utilities (section, step, info, success, fail)
│   │   └── symlink.sh        # Symlink with conflict resolution ([O]verride/[B]ackup/[S]kip)
│   ├── *_installation.sh     # Platform installers (mac, linux_arch, etc.)
│   └── {component}/          # Component setup scripts
│       └── {platform}/setup.sh
├── configs/                   # Configuration files (symlinked to home)
│   ├── rift/                 # macOS tiling WM + SketchyBar
│   ├── nvim/                 # Neovim + LazyVim
│   ├── tmux/                 # Tmux + custom scripts
│   ├── zshrc/                # Zsh + modular configs
│   ├── hypr/                 # Hyprland (Arch)
│   ├── waybar/               # Wayland status bar
│   ├── dolphin/              # KDE file manager
│   ├── ghostty/              # Terminal emulator
│   ├── starship/             # Shell prompt
│   ├── lazygit/              # Git TUI
│   └── ...
└── .dotconfig                 # User preferences (auto-generated)

Configuration Management

User preferences stored in .dotconfig:

DOT_NAME="Jordan Garcia"
DOT_EMAIL="user@example.com"
DOT_ENVIRONMENT="work|personal"
DOT_SYSTEM="mac|linux_arch|..."
DOT_YUBIKEY="ABC123..."  # Optional GPG key for git signing

---

Management Commands

bin/dot

./bin/dot -h              # Show help
./bin/dot -i              # Interactive setup
./bin/dot -l              # List available profiles
./bin/dot -m              # Select modules interactively
./bin/dot -s              # Show system detection
./bin/dot -c              # View current config
./bin/dot -e              # Open dotfiles in $EDITOR
./bin/dot --reset-config  # Clear config and start fresh
./bin/dot --reconfigure   # Re-run interactive setup

---

Post-Installation

Tmux Plugins

tmux source ~/.tmux.conf   # Reload config
# Inside tmux: <prefix> + I to install plugins

Zsh Plugins

Plugins are sourced directly from ~/.zsh/plugins/. Install via git clone:

git clone https://github.com/zsh-users/zsh-syntax-highlighting ~/.zsh/plugins/zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/plugins/zsh-autosuggestions

YubiKey Git Signing (Optional)

gpg --list-secret-keys --keyid-format=long  # Find key ID
# Provide during ./bin/dot -i or set manually

---

Development

Adding Components

1. Create setup script: script/{component}/{platform}/setup.sh
2. Add to installation array in script/{platform}_installation.sh
3. Use logging from script/common/log.sh
4. Place configs in configs/{component}/
5. New components are automatically picked up from the installation arrays

Supporting New Platforms

1. Add detection to bin/dot detect_system()
2. Create script/{platform}_installation.sh
3. Implement component scripts
4. Choose package manager (brew/apt/dnf/pacman)

---

Troubleshooting

Issue	Solution
Permission denied	Don't run with sudo - scripts handle elevation
Missing dependencies	Run platform installation script first
Config conflicts	./bin/dot --reset-config to start fresh
Tmux plugins missing	Inside tmux: <prefix> + I

---

Tested across macOS, Arch Linux, Ubuntu, Fedora, and WSL. Fork and adapt for your needs.