From Box to Productive in Thirty Minutes

A new MacBook arrives in a sealed box. Forty-five minutes later, counting from when I tear off the plastic, I'm up and running. Every app I rely on is installed. My fonts are right, my keyboard shortcuts work, the text-expansion triggers I use a hundred times a day are firing, my terminal looks exactly the way I want it to, my preferences for code versioning, my code editor, and a dozen other tools have travelled with me. Raycast, the app I hit more often than any other on this machine, is set up with the snippets and shortcuts I rely on. Wispr Flow, the voice-dictation tool I've been leaning on more and more, is configured and listening. I haven't clicked through a single Settings panel.

That's not because I'm fast. It's because the work is done by something called a dotfiles repo: a single folder, version-controlled, that captures every preference and installation choice I've made over years of using my laptop. One command rebuilds it on a fresh machine.

What follows is partly a tour of mine. Mostly it's an argument for two things: first, that a dotfiles repo is one of the most underrated tools available to anyone who cares about their computer setup; and second, that the apps that travel with mine are worth knowing about whether or not you ever set one up.

What's a dotfile, anyway?

The name comes from a Unix convention dating back roughly fifty years. Programs that needed to store user preferences would tuck them away in a hidden file, hidden because the filename began with a dot. Open a fresh Mac terminal and run ls -a in your home folder and you'll see them: .bashrc, .gitconfig, .ssh, dozens of others. Each is a small text file that some application reads when it starts up.

The convention stuck. Today, almost every serious tool stores its preferences in a text file somewhere on disk: editors, terminals, version-control systems, fuzzy finders, text expanders, productivity utilities, the lot. Some of those files start with a dot; some live inside a ~/.config/ directory; some sit deep in ~/Library/. The principle is the same: a plain-text record of how you've configured the tool, kept separately from the tool itself.

A dotfiles repo is what happens when you collect those files in one place, put them under version control (typically with git, often hosted on GitHub), and treat them as a first-class part of your setup. Every change you make is a commit. Every commit is a record. And the whole thing can be cloned onto another machine and replayed.

What you get from one (and what other approaches miss)

Once you have a dotfiles repo, the things you'd otherwise spend hours doing manually become declarative. You write down what you want once, and the repo does the rest: capture preferences across every tool, install your applications via a Homebrew (https://brew.sh/) Brewfile (https://github.com/Homebrew/homebrew-bundle) (a shopping list for your computer that installs every command-line tool, every GUI app, every font in one go), version every change as a git commit, sync between machines, and replay the entire setup when the inevitable hard-drive failure or OS reinstall comes.

The obvious alternatives all fail in interesting and predictable ways. Manual setup is slow, error-prone, and undocumented; you'll forget half of what you tweaked, and the next time round you start from scratch. The Mac App Store is partial: most apps power users actually rely on (Raycast, voice-dictation tools like Wispr Flow, text expanders, terminal emulators worth using) aren't on it at all, and the ones that are come back as apps without their configuration. Migration Assistant is opaque: it carries the entire state of your old machine across, including caches, broken extensions, login items from apps you uninstalled in 2021, and accumulated cruft you can't see and can't audit, leaving you with a sometimes faster cluttered laptop instead of a fast and clean one.

A dotfiles repo is the opposite of all three. It's deliberate (you wrote it). It's portable (it's just text and a script). It's auditable (you can read every line). And it's complete-by-design: if a setting matters to you, it's in the repo. If it isn't in the repo, it doesn't matter to you.

The apps in mine you might steal

The technical case for dotfiles is one thing. The pleasure of running them is another, and most of it comes from the apps that travel with the repo. Here are five I rely on most. None require a dotfiles setup to use; they're all worth installing on their own. The dotfiles repo just means I never have to remember to install them.

Raycast (https://www.raycast.com/) is the app I use more often than any other on my Mac. It started life as a faster, more keyboard-friendly Spotlight replacement. I was using Alfred (https://www.alfredapp.com/) which was a paid app but Raycast has grown into something closer to a personal command surface: app launcher, calculator, clipboard manager, window manager, snippet expander, plus a community extension catalogue covering Spotify, GitHub, weather, currency conversion, time-zone arithmetic, and almost anything else you can imagine. If you're still using your mouse for everything and being mildly disappointed by what comes back, give Raycast a try.

Wispr Flow (https://wisprflow.ai/) is voice dictation with an AI cleanup pass. You hold a hotkey, speak naturally (umms, false starts, mid-sentence corrections all welcome), and a clean, well-structured version of what you said appears in whatever app has focus. It's the only dictation tool I've tried that doesn't feel like a step backwards from typing. Drafting emails, capturing thoughts, talking through a paragraph instead of typing it: all of it gets faster, and I keep finding new contexts to use it in. A free free version allows for up to 2000 words per week, and the paid version is worth it if you find yourself using it more.

Claude Desktop (https://claude.ai/desktop) is a local client for the Claude family of large language models. It's a scratchpad for quick questions, brainstorming, and writing help. I use it for everything from quick calculations to drafting emails to brainstorming blog post ideas. The local client means it's always just a hotkey away, and the fact that it's built on top of the same models I use in the browser means I can have a consistent experience across contexts. The GUI is simple and clean, and the fact that it's free to use with a free account makes it an easy addition to your toolkit. For heavier work I still prefer using Claude Code in my terminal or code editor, but for quick interactions and brainstorming, the desktop client is a great way to keep the power of a large language model at your fingertips.

Espanso (https://espanso.org/) is a text expander. You define short triggers (;date, ;sig, ;email) and a nifty script swaps them for longer text as you type. Macros support dynamic content too: the current date, the clipboard contents, the output of a shell command. The savings compound — a couple of seconds per expansion times dozens of expansions a day adds up to real minutes. Cross-platform, free, open-source, and configurable in plain YAML. The dotfiles trick I'm fondest of is keeping the public snippets in one tracked file and the sensitive ones (work email addresses, phone numbers, throwaway test credentials) in a sibling file that's never committed; Espanso loads both happily, and the split is invisible at runtime.

Obsidian (https://obsidian.md/) is a note-taking app built on local Markdown files. The killer features are bidirectional links (every note can link to others, and you can see which notes link back to any given page) and a graph view that visualises the connections. Unlike Notion or Evernote, your notes live as plain text on your own disk, which means they're future-proof, version-controllable, and readable in any editor. I keep my reading notes, research threads, and writing drafts here. The plugin ecosystem is thriving, and the fact that it's built on top of Markdown means you can use it as a scratchpad for writing in any context: draft a blog post in Obsidian, then copy-paste it into your CMS with all the formatting intact.

Zotero (https://www.zotero.org/) is a reference manager. If you do any kind of research, it's a game-changer. It captures metadata from academic papers, web pages, and other sources, and keeps it all organised in a local library. You can tag items, create collections, and generate citations in any style. I annotate research papers, thesis, eBooks heavily with highlights and notes. The browser extension makes it easy to save sources as you find them, and the desktop app keeps everything synced and searchable. I can also link directly to these annotations from Obsidian, which means my research notes are always just a click away from the source material.

Bitwarden (https://bitwarden.com/) is the open-source password manager I switched to from 1Password. Free for individuals, inexpensive paid plans for teams, end-to-end encrypted, available everywhere: browser extension, desktop, mobile, CLI.

Worth an evening?

The repo is at github.com/bryanjhickey/dotfiles, if you'd like to see how the pieces fit together. It isn't the cleanest example on the internet; the popular ones have been polished for years. But it's a real working setup that takes a real laptop from sealed plastic to fully configured in about thirty minutes.

The honest pitch isn't "everyone should run my exact setup." It's that almost anyone who spends serious time on a computer eventually has more configuration than they realise, and a single source of truth for that configuration is one of the most useful things you can build for yourself. The first evening is the hardest. After that, every new machine costs you about thirty minutes — and your future self, the one whose laptop has just had a hard-drive failure on a Tuesday morning, will thank you.