Dotfiles

Reproducible macOS setup using Homebrew Bundle, GNU Stow, Oh My Zsh, Starship, nvm, rustup, LazyVim, and Gitleaks.

The repository manages:

• Command-line tools, applications, fonts, and VS Code extensions in Brewfile
• Portable shell, Git, GitHub CLI, LazyVim, editor, terminal, Herdr, Claude Code, and OpenCode configuration under stow/
• Global agent skills through the tracked stow/agents/.agents/ snapshot
• Node.js, Bun, pnpm, Rust via rustup, OpenCode, Claude Code, Claude MCP servers, and gh-stack setup through bootstrap.sh

Install on a new Mac

Run the hosted installer:

curl -fsSL https://dotfiles.aldotestino.dev/install.sh | bash

After bootstrap completes, enter ~/dotfiles and run:

make stow-dry-run
make stow
make claude-skills
make hooks

Bootstrap installs Apple's Command Line Tools and Homebrew when needed, installs Brewfile, and configures the remaining tools without linking dotfiles automatically.

The latest current Node.js release is installed by default. To use the latest LTS release instead:

NODE_VERSION='lts/*' ./bootstrap.sh

Avoid forced Homebrew Bundle cleanup during the initial migration; it may remove software not declared here.

LazyVim

The tracked Neovim configuration is based on the official LazyVim starter. Homebrew installs Neovim, Cargo installs the required tree-sitter-cli, and make stow links the starter at ~/.config/nvim.

If Neovim has existing configuration or state, follow LazyVim's installation guidance and move it aside before linking the dotfiles:

mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

The configuration directory backup is required when it already exists; the data, state, and cache backups are optional but recommended. After running make stow, start nvim to install the plugins, then run :LazyHealth as recommended by LazyVim.

Validate

make brew-check
make check
make stow-dry-run

make check runs Gitleaks, Bash and Zsh syntax checks, ShellCheck, Brewfile validation, and an isolated Stow preview. The final command previews conflicts against the current home directory. None of these commands creates links or installs packages.

Stow

Every immediate directory under stow/ is discovered automatically.

make stow
make stow-dry-run
make stow-delete

Application packages link individual files so generated logs, caches, and sessions remain outside the repository. The agents package intentionally links the complete ~/.agents directory; global skill updates may therefore modify this repository and should be reviewed before committing.

The Stow workflow never adopts existing files. Back up and compare an existing target file before resolving a conflict.

Run make claude-skills after make stow to link each skill from ~/.agents/skills into ~/.claude/skills. Existing Claude skills are left untouched; a conflicting name causes the command to stop rather than replace it.

Complete interactive setup

Authentication and machine identity are not tracked. Sign in to the services you use, including GitHub, npm, AWS, Google Cloud, Railway, gcx, Docker, Codex, Claude Code, and OpenCode.

Run make herdr-integrations after Claude Code, Codex, and OpenCode are available. Authenticate GitHub CLI and the other installed services interactively.

Linear may request OAuth authorization when its MCP server is first used. Private plugins, application licenses, Kubernetes credentials, and cloud profiles must be restored separately.

Security and local overrides

Enable the repository-local pre-commit scan in every clone and run a full scan before pushing:

make hooks
make check-secrets

Keep secrets out of tracked files. Machine-specific shell and Git settings belong in:

~/.zshrc.local
~/.gitconfig.local