christina.codes

Finally, Dotfiles I Actually Like

I've never been able to maintain dotfiles. Every few years I'd start fresh, copy-paste configs from random GitHub repos, forget what half of it did, and eventually abandon the whole thing when something broke. Rinse and repeat for about a decade. Setting up a new laptop was something I actively dreaded — hours of Googling "how to export iTerm settings" and hoping I hadn't forgotten anything important.

So I pointed Claude Code at my mess and asked it to help me build something I'd actually understand.

The result is at github.com/cchawn/dotfiles. It's nothing fancy, but it's a setup that finally makes sense to me. Friends have even started forking it to bootstrap their own, which is wild considering my previous dotfiles repos were graveyards of half-finished configs.

The Commit History Tells the Story

Looking back at my git log is a bit embarrassing. The repo starts in April 2020 with first commit, followed by zsh, then .git (yes, those are the actual commit messages...). Two years later: chore: updated config. Then nothing until 2024, where I added a custom theme, deleted it, tried asdf, switched to mise, gave up on mise, and went back to random version managers. 😅

Then I started using Claude Code, and the commit history changes completely. Instead of vague commits every few months, there's a steady stream of focused changes:

2025-07-17 feat: add mise
2025-07-17 feat: add .gitignore_global
2025-07-31 chore: reorganize files
2025-07-31 feat: better git config
2025-07-31 feat: better ghostty config
2025-08-08 feat: add .claude files
2025-08-24 feat: add install script
2025-08-26 fix: add gpg signing and alphabetize .gitconfig
2025-09-29 feat: add ssh public key for commit signing with 1pass
2025-10-23 feat: add zed config

That's more meaningful commits in three months than the previous four years combined. And crucially, each one was a deliberate improvement I understood, not a copy-paste I hoped would work.

How I Actually Built It

Phase 1: Reorganizing the Mess (July 2025)

I started by showing Claude my existing dotfiles and asking for help organizing them. The first suggestion was simple: separate configs by tool into a config/ directory instead of having everything scattered in the root.

This led to the structure I still use:

  • config/git/: git settings and aliases
  • config/ghostty/: terminal config
  • config/starship.toml: prompt customization
  • config/mise/: version management
  • zsh/: shell configuration
  • private/: work-specific settings (git-ignored)

Phase 2: The Install Script (August 2025)

The feat: add install script commit was a turning point. My previous dotfiles repos had READMEs that said things like "copy these files to your home directory" which I never actually did correctly.

I asked Claude for an install script that would handle symlinks, back up existing files, and not break if I ran it twice. The first version worked, but I had to coax out the edge cases:

  • "What if I have work-specific config I don't want in the repo?"
  • "How do I avoid committing my email address and signing key?"
  • "What happens if the script runs twice?"

None of this happened in one session. The work config issue came up when I ran the install script on my work laptop and realized half my settings assumed my personal machine. The template system came after I accidentally pushed a commit with my work email and had to rewrite history.

The private/ directory is git-ignored and conditionally sourced. The personal details became a template system:

if [[ ! -f "$DOTFILES_DIR/private/git/user.gitconfig" ]]; then
    log "Creating user git config from template..."
    cp "$DOTFILES_DIR/config/git/user.gitconfig.template" \
       "$DOTFILES_DIR/private/git/user.gitconfig"
    echo "⚠️  Please edit with your git user details"
fi

The script timestamps backups, creates missing directories, and generates git user config from a template so I don't accidentally commit my email address. These are all things I would have forgotten to handle myself — but Claude didn't suggest them unprompted either. The good solutions came from me hitting real problems on real machines and then asking Claude how to fix them.

Phase 3: Claude Code Skills (Now!)

The most recent additions are Claude Code skills — custom commands for tools I use at work:

2026-01-23 feat: add jira cli skill
2026-01-23 feat: add sentry-cli skill
2026-01-23 feat: add Claude Code status line

These skills teach Claude how to interact with Jira and Sentry so I can ask questions about tickets or errors without leaving my terminal. This is the pattern coming full circle: the dotfiles repo now extends the tool I used to build it.

The Tools I'm Actually Using

Ghostty

I'd been on iTerm2 forever, mostly out of inertia. A colleague suggested Ghostty and the config is just a text file instead of a preferences pane I have to dig through. Sold.

mise for Version Management

I'd been wanting to try mise for a while. It replaced the grab-bag of version managers I had for Node, Python, Ruby, and Deno — and it handles Claude Code itself.

Starship Prompt

Starship handles my prompt. I went a bit overboard with a custom Dracula theme and emoji-based git status indicators (🌷 for up-to-date, 💀 for diverged, 💅 for staged changes). It's more playful than minimal, but it's mine, and I love her!

Prompting Is a Skill (Who Knew)

Prompting is a skill, and I'm still figuring it out. My first attempts were way too vague ("write an install script") and I'd get something that technically worked but missed edge cases I cared about. When I got specific ("back up existing files, support dry-run mode, make it idempotent"), the output was immediately usable.

The other thing — and this surprised me — I actually understand my setup now. When Claude suggested a tool, I'd ask why. "Why mise instead of asdf?" "What does this zsh option do?" "Why histogram for the diff algorithm?" This turned config generation into a conversation, and I retained way more than I ever did copy-pasting from StackOverflow.

My favourite trick: asking Claude to "show me your source." AI is known to make things up, so when Claude suggests a specific git config option or shell setting, I'll ask for documentation links. It runs a web search and gives me the actual docs to verify against. This caught a few hallucinated options and helped me understand the tradeoffs better than if I'd just trusted the output blindly.

I still had to test everything myself. Claude doesn't know my specific macOS version or what's already in my home directory. And verify includes checking that the thing Claude confidently explained actually exists.

The Repo

github.com/cchawn/dotfiles

73 commits and counting. It's a Brewfile, zsh config, an install script, and configs for the tools I mentioned. But for the first time in a decade of trying, I know what all of it does — and more importantly, I'm not dreading the next time I need to change something.