macOS dotfiles

Opinionated macOS development environment with one shared Tokyo Night theme.

Application configs live in top-level directories (zsh/, nvim/, ghostty/, herdr/, superfile/, and pi/). Setup scripts, tests, and shared theme data stay separate. Installer handles app-specific paths and backs up existing configs before it links them.

Included tools

Core tools

• bat — Cat replacement with syntax highlighting.
• eza — Modern replacement for ls.
• fd — Fast, user-friendly file finder.
• fzf — Fuzzy finder for files and command history.
• Neovim — Extensible text editor.
• nvm — Node.js version manager.
• ripgrep — Fast recursive text search.
• Starship — Cross-shell prompt.
• Superfile — Terminal file manager with custom hotkeys and Tokyo Night theme.
• zoxide — Frecency-based directory navigation.
• Zsh — Interactive shell.

Optional tools

• Bun — JavaScript runtime, package manager, test runner, and bundler.
• Herdr — Terminal multiplexer for persistent workspaces and coding agents.
• Ghostty — GPU-accelerated terminal.
• Handy — Offline speech-to-text app; first launch needs microphone and accessibility permissions.

Installed with Ghostty

• JetBrainsMono Nerd Font — Nerd Font installed with Ghostty.

Zsh plugins

• zsh-autosuggestions — Suggests commands from history as you type.
• zsh-history-substring-search — Searches history by typed text with Up/Down.
• zsh-vi-mode — Adds Vim-style command-line editing modes.
• fast-syntax-highlighting — Highlights shell syntax while editing commands.

Runtime-managed tools

• Node.js — JavaScript runtime; fresh installs use version 22, and Pi needs version 22.19 or newer.
• Pi — Terminal coding agent installed with its managed installer.

Neovim plugins

• LazyVim — Opinionated Neovim setup and plugin collection.
• lazy.nvim — Plugin manager used by LazyVim.
• nvim-lspconfig — Neovim language server configurations.
• nvim-treesitter — Treesitter parsing and highlighting for Neovim.
• blink.cmp — Completion engine for Neovim.
• gitsigns.nvim — Git change indicators for Neovim.

Superfile integrations

• Vim-like Superfile hotkeys — Uses h/j/k/l, / search, and familiar copy/paste keys.
• Superfile Zoxide plugin — Enables frequent-directory navigation with z.
• Superfile Tokyo Night theme — Uses colors from the shared theme configuration.

Theme

• Tokyo Night — Shared dark palette used by Ghostty, Herdr, Neovim, Superfile, and Starship.

Program metadata lives in config/programs.zsh. Add a supported Homebrew formula or cask there; installer, uninstaller, Brewfile, and this inventory use that data. Zsh plugins also use the same records for prompts and loading. Theme colors and metadata live in theme/tokyo-night.sh. Run scripts/render-configs.sh to regenerate Brewfile, this inventory, and app configuration files.

Install

Requirements: macOS 13+. Install Apple Command Line Tools first if missing; Git may open the installer prompt on a new Mac:

xcode-select --install

Wait for installation to finish, then clone and run setup. Installer installs Homebrew if missing.

git clone https://github.com/marcosgilf/dotfiles ~/dotfiles
~/dotfiles/install.sh

Installer:

• installs configured core programs; offers configured optional programs and Zsh plugins; preserves saved plugin choices and detects existing plugin checkouts on updates
• preserves an existing nvm default/active version; sets Node.js 22 as default when no nvm Node is selected
• installs or migrates Pi with its managed installer when needed, then runs pi update --all when Node.js is 22.19+; warns and skips Pi otherwise
• prints dependency progress and first-install launch steps; reruns report Update completed.
• renders configuration files from the shared theme
• links managed files into standard macOS config paths
• preserves existing configs as timestamped backups
• preserves untracked local zsh functions under zsh/functions/local/
• is safe to run again; it never pulls or overwrites managed repositories

Keep this repository at a stable path because managed symlinks point into it.

Use

open -a Ghostty
open -a Handy
herdr
pi
spf
nvim

Start a new shell after installation. Neovim plugins install on first launch; nvim/lazy-lock.json records their versions.

Update

cd ~/dotfiles
git pull
./install.sh

Run :Lazy sync inside Neovim when intentionally updating plugins, then commit nvim/lazy-lock.json.

Test

./scripts/test-install.sh

Smoke test stubs Homebrew, NVM, npm, Pi installer, and Zsh plugins; uses temporary home directories.

Privacy boundary

Only portable configuration belongs here. Never add shell history, cloud or Git credentials, Herdr sessions/logs, local environment files, private keys, or work-specific commands. Put machine-only functions in zsh/functions/local/; that directory is ignored.