Dotfiles

Personal dotfiles for a minimal, reproducible macOS development environment.

New here? Check out the Learning Guide — a walkthrough of every tool in this repo with the commands worth knowing, power combos, and a suggested learning order.

Contents

• Brewfile — Homebrew package and cask list
• LEARNING_GUIDE.md — Tool-by-tool guide with commands, tips, and workflows
• install.sh — Installer script that creates symlinks and provisions Homebrew
• gitconfig — Git config
• zprofile — Login shell profile (Homebrew shellenv)
• zshrc — Interactive shell config (fnm, rbenv, direnv, starship)
• config/starship.toml — Starship prompt configuration

Overview

This repo provides a small set of dotfiles and an installer to:

• Symlink configuration files into your $HOME
• Install Homebrew (if missing)
• Run brew bundle using the provided Brewfile

Installation

Run the installer from the repo root:

bash ./install.sh

The installer script install.sh sets up a runtime variable DOTFILES_DIR and uses the helper function link() to create symlinks and back up existing files.

What gets linked by default:

• zprofile -> ~/.zprofile
• zshrc -> ~/.zshrc
• gitconfig -> ~/.gitconfig
• config/starship.toml -> ~/.config/starship.toml

The script will install Homebrew if it is not present, then run:

• brew update
• brew bundle --file "$DOTFILES_DIR/Brewfile" (uses Brewfile)
• brew upgrade --cask
• brew cleanup

Updating Packages

You don't need to rerun the full installer just to pick up Brewfile changes. From the repo directory:

brew bundle --file Brewfile

This installs anything new in the Brewfile. To also remove packages you've deleted from it:

brew bundle --file Brewfile --cleanup

For a full machine refresh (relink configs, update Homebrew, upgrade casks, clean up), run the installer instead:

bash ./install.sh

Behavior & Safety

• If a destination file already symlinks to the correct dotfiles source, the installer skips it (idempotent re-runs).
• If a destination is a symlink to somewhere else, its resolved content is copied to a timestamped backup (file.bak.<epoch>) before relinking.
• If a destination is a regular file, it is moved to a timestamped backup (file.bak.<epoch>).
• Symlinks are created with ln -s so the source repo remains authoritative.
• See the implementation of link() for exact behavior.

Customization

• Edit config/starship.toml to change prompt appearance.
• Modify Brewfile to change installed packages and casks.
• Update gitconfig, zprofile, and zshrc as desired.

Shell Aliases

The shell config exports CLICOLOR=1 for colorized ls output on macOS and defines handy aliases:

Alias	Command	Description
ll	ls -lhaG	Long listing, human sizes, hidden files, color
la	ls -aG	Hidden files, compact
l	ls -G	Quick color listing

Shell Helpers

The shell config in zshrc includes several helper functions:

gcma — AI Commit Messages

git add .
gcma                          # uses your saved default agent
gcma claude                   # override with Claude Code
gcma codex                    # override with Codex
gcma --set-default claude     # change the saved default

• On first run, gcma prompts you to choose an agent (claude or codex) and saves it as the default in ~/.config/gcma/default_agent.
• Pass an agent name to override the default for a single run.
• Use gcma --set-default <agent> to change the saved default anytime.
• Supported values are codex, claude, and claude-code.

gpr — AI Pull Requests

Creates a GitHub PR with an AI-generated title and description from your commit history.

gpr                           # create PR against main
gpr develop                   # create PR against a different base branch

Uses the same default AI agent as gcma (set via gcma --set-default <agent>). If no default is saved, it prompts you to choose one on first run. The agent summarizes your commits into a concise title and markdown body, then calls gh pr create.

proj — Fuzzy Project Switcher

Fuzzy-find and cd into a project directory using fd + fzf.

proj                          # search from $HOME
proj ~/Projects               # search from a specific root

port — Port Inspector

Show what process is using a given port.

port 3000                     # see what's running on port 3000
port 8080                     # check port 8080

cleanup-bak — Remove Installer Backups

Remove the *.bak.* backup files that install.sh creates when relinking dotfiles.

cleanup-bak --dry-run         # list what would be deleted
cleanup-bak                   # prints and deletes each backup file

The file list is read out of install.sh at run time rather than duplicated here, so adding a dotfile to the installer extends the cleanup automatically. It previously named four paths by hand while install.sh linked seven, and backups of ~/.ssh/config and ~/.claude/CLAUDE.md were silently never cleaned.

dotup — Update Dotfiles

Pull the latest dotfiles, run brew bundle, and re-source your shell config in one command.

dotup

swlogs — Tail Sweep Worker Logs

Tail all parallel sweep worker logs from Granite Harbor backtest sweeps. Automatically finds the most recent sweep_logs_* directory in $TMPDIR, or accepts an explicit path.

swlogs              # auto-detect latest sweep logs
swlogs /tmp/sweep_logs_20260405

Revert / Uninstall

To revert changes made by the installer:

1. Remove the symlinks created in your home directory (e.g., ~/.zshrc, ~/.gitconfig, etc.).
2. Restore backups *.bak.* which the installer created.
3. Optionally uninstall Homebrew packages via brew uninstall / brew bundle --file Brewfile --no-upgrade as needed.

Notes

• The prompt relies on starship and its config at config/starship.toml.
• zshrc initializes rbenv, direnv, and starship, exports CLICOLOR, and defines ll/la/l aliases.
• AWS CLI (awscli) is included for interacting with AWS services (S3, EC2, IAM, etc.). Configure with aws configure.
• Supabase CLI is included for local development and managing Supabase projects.
• uv is the Python package/venv tool — it replaces pip, poetry, and pyenv.
• cairo is a native graphics library with no CLI of its own — Python plotting/imaging packages (matplotlib, pycairo, cairosvg) link against it at build time.
• Tailscale (cask tailscale-app) provides the mesh VPN behind the studio and laptop SSH hosts in config/ssh/config.
• pnpm is included as a fast, disk-efficient alternative to npm.
• Editors: VS Code (primary), Sublime Text, Cursor, and Zed are all installed via casks.
• Google Chrome and Granola (AI meeting notes) are installed via casks; both auto-update themselves, so brew upgrade will skip them.
• Conductor runs parallel Claude Code sessions; its SSH entries load via the Include ~/.ssh/conductor_config line at the top of config/ssh/config, which is generated per machine and not tracked here.
• Hack Nerd Font is installed for proper Starship prompt glyphs — set it as your terminal font.

Files & Symbols

• Brewfile
• install.sh — see DOTFILES_DIR, link()
• gitconfig
• zprofile
• zshrc
• config/starship.toml

License

MIT