This week I made my dotfiles public. The repo is new and still changes every week. It holds my shell, my editor, my window manager, the instructions my AI tools load, and a Brewfile of the tools I use.
Before I pushed it, I read the whole thing back. I expected configuration. What I found was a record of decisions: what I use, how I use it, and what I chose to leave out.
A Brewfile that refuses to be a dump
The first two lines of my Brewfile are the rule for the rest of it:
Tools chosen on purpose for this Mac. […] Add a line only when a tool is adopted; this is not a dump of everything installed.
That rule does most of the work. Installing a tool is easy. Adopting it is a separate step, and only the second one earns a line. So the Brewfile reads like a short list of things I rely on, grouped by what they are for: shell, window management, editor, cloud, languages.
Several lines carry a comment that says why the tool is there. ripgrep is there because LazyVim needs it for search. eza is there because my ll and tree aliases call it. powerlevel10k and two zsh plugins are there because my .zshrc sources them. Each comment ties a tool to something else in the repo that would break without it. If I ever remove the thing that needs it, the tool should go too.
Recently I added four tools at once: ripgrep, bat, tree-sitter-cli and lazygit. I needed them for learning Neovim and fzf. I held back the cloud tooling I will need later, because I am not at that stage yet. The Brewfile tracks where I am today.
The small changes add up
Most of the history is small. I changed the focus border on my window manager several times before it felt right, and I tried more than one prompt style before settling on Powerlevel10k Lean. Those changes matter to nobody else. I look at that border and that prompt all day, and a default is someone else’s guess about what I want. Each change replaced a guess with a choice.
The workflow choices are in there too. I added a rule to the README for AI agent skills: before installing one, decide whether every session needs it or only one project does. I wrote it after installing a large bundle of community skills before deciding where they should live. A global skill loads into every session, so the README now says to start at project level and move a skill into the dotfiles only when every session needs it.
That rule is a judgement, and I had to get it wrong once before I could write it down.
Why this matters more now
New tools arrive faster than I can evaluate them, and AI is speeding that up. A small tool used to be a project. With an agent it can be an afternoon, for me and for everyone else, so the number of tools is about to climb fast.
When tools are cheap, choosing between them is the scarce part. Anyone can install everything. The skill is knowing what earns a place, wiring it into a workflow that fits how you think, and dropping what does not. I wrote about this in how I use AI: I care about workflows more than prompts, because a good prompt helps once and a good workflow helps every day. Dotfiles are where that workflow becomes concrete and repeatable.
There is a second reason to keep them. My AI tools now read my dotfiles too. The claude package holds the global instructions every Claude Code session loads, and the agents package holds the skills those sessions can use. Personal taste used to shape only my own setup. It now shapes how the agents working for me behave as well.
What a snapshot cannot show
A snapshot captures what I chose. It shows why I rejected an alternative only when I wrote a comment or a commit message at the time.
It also goes stale. A tool I stop using keeps its line until I notice and delete it. The rule says to add a line when a tool is adopted. Nothing yet tells me when a tool has been abandoned.
And it is mine. Copying someone else’s dotfiles gives you their decisions without the reasons behind them. Other people’s setups are a good source of ideas, and I read them for that. The setup only fits after I have made each choice myself.
I expect the repo to keep changing every week, and the history is the useful part, because it shows how my tools and my workflow moved over time.