# Dotfiles, Revisited

> Three months and twelve tagged versions later: what changed in my dotfiles since the original MacBook setup guide, and why.

- **Published:** 2026-03-21
- **Article Type:** default
- **Tags:** [dotfiles](https://janwillemaltink.com/tags/dotfiles/), [terminal](https://janwillemaltink.com/tags/terminal/), [zsh](https://janwillemaltink.com/tags/zsh/), [homebrew](https://janwillemaltink.com/tags/homebrew/), [developer-setup](https://janwillemaltink.com/tags/developer-setup/), [tmux](https://janwillemaltink.com/tags/tmux/)
- **URL:** https://janwillemaltink.com/writings/dotfiles-revisited/

---

_Last December I published a [setup guide](/writings/new-macbook-guide) for configuring a fresh MacBook, built around the first version of my [dotfiles](https://github.com/jwa91/dotfiles). That guide ended with: "this repo will probably change often." Three months and twelve tagged versions later, that prediction held up. The setup scripts from the original post no longer exist, most functions have been renamed, and the toolchain looks quite different. This is an overview of what changed and why._

<TOC />

## One Bootstrap to Rule Them All

The original dotfiles had three separate setup scripts: `install-zsh.sh` for the shell environment, `install-tools.sh` for developer tools, and `install-apps.sh` plus `link-apps.sh` for GUI applications and symlinks. Each had its own Brewfile, its own argument parsing, its own logging helpers. It worked, but it meant maintaining three parallel flows that all did fundamentally the same thing: install packages and create symlinks.

v2 replaced all of that with a single `setup/bootstrap.sh`. One script, one Brewfile, one entry point.

```bash
./setup/bootstrap.sh              # full setup
./setup/bootstrap.sh --dry-run    # preview without changes
./setup/bootstrap.sh --no-brew    # skip Homebrew, just symlink
./setup/bootstrap.sh --reset      # remove and recreate all symlinks
```

The root `Brewfile` became the canonical source of truth for everything Homebrew manages: CLI tools, language runtimes, fonts, GUI apps. A `brewsync` alias keeps the system in sync:

```bash
alias brewsync='brew bundle --file="$DOTFILES_DIR/Brewfile" --cleanup'
```

The `--cleanup` flag removes anything installed by Homebrew that isn't in the Brewfile. One command, one source of truth, no drift.

For the handful of tools that can't go through Homebrew (1Password desktop, Xcode CLI tools, Docker Desktop), there's a `setup/manual-installs.txt` file that bootstrap prints at the end as a checklist.[^2]

## Terminal-Aware Configuration

One of the more interesting changes was making the shell aware of which terminal it's running in. The problem: I use Ghostty on my MacBook, but occasionally SSH in from my phone via Termius and mosh. Mosh miscalculates the width of Nerd Font icons, which breaks the Starship prompt layout.

The fix was a `TERM_PROGRAM` switch in `.zshenv`:

```bash
case "$TERM_PROGRAM" in
    vscode)
        export STARSHIP_CONFIG="$XDG_CONFIG_HOME/starship.toml"
        export EDITOR="cursor --wait"
        ;;
    ghostty)
        export STARSHIP_CONFIG="$XDG_CONFIG_HOME/starship.toml"
        export EDITOR="fresh"
        ;;
    *)
        export STARSHIP_CONFIG="$CONFIG_DIR/starship-mobile.toml"
        export EDITOR="micro"
        ;;
esac
```

Desktop terminals get the full Starship prompt with Nerd Font icons and language detection. Everything else gets a stripped-down variant: just the directory, git branch, and a minimal `>` character. No icons, no language segments, no clock. It renders differently, but it works everywhere.

The same switch routes `$EDITOR`. Cursor when inside VS Code's integrated terminal, Fresh (a lightweight terminal editor) in Ghostty, and micro as the universal fallback.[^3]

## A New Naming Convention

At some point I realized my aliases and functions followed no consistent pattern. `edit_zsh`, `load_key`, `clean_pycache`. Different styles, different verb positions, inconsistent separators. I renamed everything to follow an action-prefix convention, mashed together without underscores:

| Before | After | Pattern |
| --- | --- | --- |
| `edit_zsh` | `ezsh` | e + target |
| `edit_dotfiles` | `edots` | e + target |
| `load_key` | `key` | just the noun |
| `zsh-doctor` | `zshdoctor` | action + target |
| `clean_pycache` | `pyclean` | action + target |
| `pass` | `mkpass` | mk + thing |

The `e` prefix opens things in the terminal-aware `_eopen` helper. `cd`-prefixed versions navigate instead:

```bash
ezsh()    { _eopen "$ZSH_DIR"; }
edots()   { _eopen "$DOTFILES_DIR"; }
cdzsh()   { builtin cd "$ZSH_DIR"; }
cddots()  { builtin cd "$DOTFILES_DIR"; }
```

Navigation also got simpler: `..`, `...`, `....`, and `.....` for going up one to four directories.

And suffix aliases, which might be my favorite small addition: type the name of a `.md` or `.json` file and it opens in your editor. Type a `.pdf` or `.png` and it opens in the default viewer. No need to prefix with a command.

```bash
# Type "README.md" → opens in terminal-aware editor
alias -s md='_eopen'
alias -s json='_eopen'

# Type "document.pdf" → opens in Preview
alias -s pdf='open'
alias -s png='open'
```

## New Tools in the Toolchain

Several new tools earned a permanent spot in the Brewfile since v1:

**Atuin** replaced the built-in zsh history search. It stores shell history in a SQLite database with full-text search, timestamps, and directory context. `Ctrl-R` now opens an interactive search that's significantly better than the default reverse-i-search. I also configured proper zsh history options (`EXTENDED_HISTORY`, `HIST_IGNORE_ALL_DUPS`, `SHARE_HISTORY`) that should have been there from the start.

**Zoxide** replaced manual `cd` for frequently visited directories. It tracks usage with a frecency algorithm and lets you jump with partial matches: `z dot` takes me to `~/dotfiles`, `z web` to the website repo. The `zi` variant opens an interactive fzf picker.

**Yazi** was added as a terminal file manager. It renders a three-pane directory view with file previews and supports the gruvbox-material theme that matches the rest of my terminal. I use it for quick visual exploration when I need a birds-eye view of a directory structure.

**Prek** replaced pre-commit. It's a Rust-based drop-in replacement that reads the same `.pre-commit-config.yaml` but runs noticeably faster.

**Biome** was added as a global fallback formatter and linter. Project-local installs take priority, but having it globally means I can format a scratch file without setting up a project first.

I also added a `getmd` shell function that fetches clean markdown from any URL via the defuddle.md API and copies it to the clipboard:

```bash
getmd https://some-documentation-page.com
# ✓ Copied 1482 words to clipboard
```

Useful for pulling documentation into notes or LLM context windows.

## Defining Boundaries

One of the less obvious but more important changes was deciding what _doesn't_ belong in dotfiles.

The v1 repo contained Claude Code agent definitions, custom commands, and instruction files alongside the configuration. It had a Claude Desktop config template. It had Codex's `instructions.md`. All of these are agent resources, not configuration, and they evolve on a completely different cadence than shell aliases or editor settings.

In v2.5.0 I drew a clear line: this repo manages classic config files only. Agent resources (skills, instructions, commands, rules) belong in the projects they serve, not in a global dotfiles repo. Claude Code's directory went from containing settings, agents, commands, and a README to just `settings.json`. Codex went from config, instructions, and README to just `config.toml`. The Claude Desktop example config was removed entirely; the app manages its own config at the default location.

The boundary made the repo easier to reason about. If something lives in `config/`, it's a config file that gets symlinked into place.

## Quality Gates

v2.1.0 introduced two git hooks that enforce discipline on the repo itself.

A **commit-msg hook** requires conventional commit format. Every commit starts with a type prefix: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. This keeps the git log scannable and makes changelog writing straightforward.

A **pre-push guard** blocks pushes to `main` unless a version tag is set on HEAD and the `CHANGELOG.md` contains a matching entry. This forces me to tag a version and write a changelog entry before publishing. It's a small amount of friction that prevents sloppy releases.

## Things That Came and Went

Not everything stuck.

The `cw` command suite was one of the bigger additions in v2.0.0: it launched Claude Code sessions in isolated git worktrees inside tmux, with fzf session picking, merge-aware pruning, and Apple Notes sync for mobile reconnect. It was removed entirely in v2.6.0. Claude Code's built-in worktree support made most of it redundant, and the Apple Notes sync was too fragile to rely on.

Similarly, `tproject` (a tmux function that created a predefined three-pane layout for coding sessions) was removed. I found I never used it the same way twice. Manual pane splitting was simpler.

The `secrets.zsh` mechanism was removed in v2.0.1. It was a file-based approach to loading API keys, requiring a `secrets.zsh` file outside of version control. The `key` function (originally `load_key`) already handled this better by pulling secrets directly from 1Password at runtime via `op read`. No files to manage, no sync to worry about.

## tmux Overhaul

The tmux configuration was significantly reworked. The prefix changed from `Ctrl-b` to `Ctrl-Space`, which avoids conflicts with Ghostty shortcuts, shell bindings, and Raycast hyperkeys.[^4]

Copy mode now uses vi keybindings, with `v` for selection and `y` to yank to the system clipboard via `pbcopy`. The config sets `OUTER_TERM` as an environment variable so new shells inside tmux know which terminal launched the server. Windows renumber automatically when one is closed, and `prefix + r` reloads the config in place.

The biggest functional addition was `ccbot`, which manages persistent Claude Code sessions connected to Telegram bots via tmux. Each project gets a detached session, its own bot token pulled from 1Password, and zsh tab completion for project names and running sessions. I wrote about this separately in [Editing a Website from Telegram](/writings/editing-a-website-from-telegram).

## What Stayed the Same

For everything that changed, the foundation from the original guide held up. Homebrew manages all packages. 1Password is the SSH agent and the secret store. Zsh with Starship is the shell. Ghostty is the terminal. The `.ssh/config` still routes everything through 1Password's agent socket.

The philosophy held too: version-control your configuration, symlink everything into place, make setup reproducible from a single command. What changed was the execution: better structure, clearer boundaries, and a few months of actually living with the choices. Dotfiles are never really done, but the current version feels like a solid foundation to iterate on. The repo is at [github.com/jwa91/dotfiles](https://github.com/jwa91/dotfiles), currently at v2.12.0.

<p class="text-center mt-8">\- Jan Willem</p>

[^2]: 1Password's desktop app needs its own installer for biometrics and browser integration to work correctly. The CLI (`1password-cli`) installs fine from Homebrew, but the GUI app is an exception.
[^3]: tmux complicates this because it overrides `TERM_PROGRAM`. The workaround: `tmux.conf` sets an `OUTER_TERM` environment variable to the terminal that launched the tmux server, and `.zshenv` checks that variable when running inside tmux.
[^4]: `Ctrl-b` conflicts with the "backward one character" shell binding. `Ctrl-a` is even worse because it conflicts with "beginning of line." `Ctrl-Space` has no default binding in most shells or terminal apps, making it a clean choice.