⚡️ Eneko's Dotfiles

My personal dotfiles for macOS, managed cleanly with GNU Stow. This setup is heavily optimized for terminal power users, featuring a modern Rust-based CLI stack, Neovim (LazyVim), and Starship prompt.

✨ Features

• Shell: Zsh powered by Starship for a blazing fast, cross-shell prompt.
• Dotfile Manager: GNU Stow for clean, symlink-based management.
• Modern CLI Stack:
  • fzf for fuzzy finding.
  • eza as a modern replacement for ls.
  • bat as a syntax-highlighting replacement for cat.
  • fd as a faster, friendlier find.
  • ripgrep as an incredibly fast replacement for grep.
  • zoxide for smarter directory navigation.
• Git: Configured with git-delta for syntax-highlighted, side-by-side diffs, plus a global .gitignore.
• Tmux: Well-documented, customized configuration with Ctrl-a prefix, vim-bindings, and sensible split shortcuts.
• Multiplexer: herdr with a Ctrl-` prefix, prefix-free Ctrl-h/j/k/l pane nav, and two fzf pickers bound over it — see herdr/README.md.
• Editor: Neovim configured via LazyVim.
• Agent guardrails: Claude Code hooks that stop the cd x && y anti-pattern, protect hand-written PR descriptions, and keep agents from commenting on GitHub or Linear — see claude/README.md.

---

🚀 Installation

1. Prerequisites

Ensure you have Homebrew installed on your Mac.

If you don't want to install dependencies manually, you can use the included Brewfile:

brew bundle --file=~/dotfiles/brew/Brewfile

Or install the core packages manually:

brew install stow starship fzf eza bat fd ripgrep git-delta zoxide neovim tmux

2. Clone the Repository

Clone this repository into your home directory:

git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles

3. Setup Secrets (Important 🔒)

For security, API keys and access tokens are not committed to this repository. Before starting your shell, create a ~/.zsecrets file in your home directory:

touch ~/.zsecrets
chmod 600 ~/.zsecrets

Add your personal exports to this file (e.g., DigitalOcean, Hetzner, Gemini tokens):

# ~/.zsecrets example
export DO_TOKEN="your_token_here"
export GEMINI_API_KEY="your_api_key_here"

Note: Your .zshrc is configured to automatically source this file if it exists.

4. Symlink with Stow

Use GNU Stow to symlink the configurations into your home directory. Run this from inside the ~/dotfiles directory:

stow zsh
stow git
stow nvim
stow tmux
stow herdr
stow ripgrep
stow --adopt claude
stow iterm2
stow local

After stow iterm2, run ./iterm2/install.sh (with iTerm2 closed) to apply the "Evangelion Dark" preset as the Default profile.

After stow herdr, install the plugins its keymap binds to and reload — the plugin list itself is machine state and isn't committed. See herdr/README.md for the commands and the full keymap.

claude needs --adopt because ~/.claude/hooks/ normally already exists with files in it; check git diff afterwards in case adopt pulled a stale local copy over the repo's. The guards need bun on the machine. See claude/README.md for what each one blocks and the settings.json snippet that wires them up.

The local package symlinks two CLIs into ~/.local/bin:

• zz — zoxide-based command runner with optional git worktree jumping (e.g. zz proj npm start or zz data@fix-foo pnpm test). Source in ~/eneko_projects/zz.
• wt — git worktree manager with per-worktree port + Postgres isolation. Service profiles (ports, DB vars, install/migrate commands) are not committed; they live in ~/.config/wt/config on each machine. Run wt help for the config format.
• diff-preview — renders the current repo's diff as a dark-themed HTML page and opens it in the browser. Needs its deps (not committed):

  cd ~/.local/share/diff-preview && npm ci

To install everything at once:

stow */

Restart your terminal, and you're good to go! 🎉

---

🛠️ How to Manage Dotfiles with Stow

GNU Stow works by mirroring the directory structure of the package into the target directory (by default, the parent directory ~/).

Adding a new configuration

If you want to add a new tool, say tmux, follow these steps:

1. Create a folder for it in the dotfiles repo:

   mkdir -p ~/dotfiles/tmux

2. Move your existing config into that folder, preserving the expected path relative to your home directory:

   mv ~/.tmux.conf ~/dotfiles/tmux/

3. Run stow to create the symlink:

   cd ~/dotfiles
   stow tmux

Removing a configuration

To remove the symlinks for a specific package, use the -D (delete) flag:

stow -D zsh

📁 Repository Structure

~/dotfiles
├── brew/
│   └── Brewfile         # Homebrew declarative package list
├── claude/
│   ├── README.md         # What each hook blocks + settings.json wiring
│   └── .claude/hooks/    # PreToolUse guards (bun) + iTerm2 tab title
├── git/
│   ├── .gitconfig
│   └── .gitignore_global
├── herdr/
│   ├── README.md         # Keymap rationale + plugin install commands
│   └── .config/herdr/
│       └── config.toml   # Prefix, pane nav, theme, plugin keybindings
├── nvim/
│   └── .config/
│       └── nvim/        # LazyVim setup
├── iterm2/
│   ├── install.sh       # Apply preset as Default profile (ignored by stow)
│   └── Library/Application Support/iTerm2/ColorPresets/
│       └── Evangelion Dark.itermcolors   # Matches Zed's Evangelion Dark theme
├── ripgrep/
│   └── .ripgreprc       # Ripgrep smart case and ignore config
├── tmux/
│   └── .tmux.conf       # Tmux configuration and shortcuts
└── zsh/
    └── .zshrc