ryanb/dotfiles: A Zsh Setup for Mac OS X, Plus a Claude Code Plugin

What ryanb/dotfiles is, and who it is for

This is one person's command line configuration, published so other people can copy it. The README describes it as config files that "set up Mac OS X command line the way I like it using Zsh". That sentence is the honest scope statement. The repository is not a framework, not a package, and not a cross-platform installer. It is a set of files for zsh, bash, completions, gem, git, irb, rails, and vim, with a shell script that copies them into your home directory.

The intended user is someone on a Mac who wants a working Zsh environment with a few opinionated conveniences and is willing to read the files. If you already maintain your own dotfiles, the value here is in specific pieces rather than the whole set: the c and h directory jump commands, the git branch prompt, and the gw branch switcher. If you are new to shell configuration entirely, the repository is small enough to read end to end, which is unusual and worth something.

The README points to an older branch for people who want the Oh My Zsh version, which tells you the current master deliberately dropped that dependency. That is a design choice, not an accident, and it means the current configuration has fewer moving parts to trace when something breaks.

A second audience has appeared more recently. The claude/ directory is a Claude Code plugin, and the README documents it in as much detail as the shell configuration. Anyone using Claude Code who wants prebuilt workflows for git bisect, interactive rebase, or pull request triage may find the plugin more relevant than the dotfiles themselves.

How the install script and the c and h shortcuts work

The mechanism is a copy, not a symlink farm. Running bin/install copies files into your home directory, and the README states it will prompt before replacing anything that already exists. That prompt is the safety net. There is no manifest, no state file, and no dry-run flag mentioned anywhere in the README, so the only way to know what will be written is to read the script and compare the top-level entries against what you already have.

The user-facing feature is directory navigation. The README explains that the author keeps coding projects in ~/code, and the c command reaches that directory with tab completion. Typing c railsca followed by tab completes to a project under that path. With no argument, c opens fzf so you can fuzzy-find a directory instead. The h command does the same thing against the home path.

The search path is configurable through CODE_PATH, and the README is explicit about one constraint: the first entry must be the base one. The example sets it to $HOME/code followed by a second directory of episodes. Order matters because the first path is treated as the root.

For git, the current branch name appears in the prompt when you are inside a repository. The gw command switches branches through fzf, and the README notes a specific behaviour worth knowing: if the branch is already checked out in a worktree, gw changes directory to that worktree instead of switching in place. That detail is the kind of thing you only learn by reading the README or by being surprised by it.

The Claude Code side works differently. It is a plugin registered through a marketplace command, and it ships twelve skills with names like bisect, dependabot-prs, fix-all, gfix, interview, pr-feedback, pr-pending-feedback, rebase, review-queue, standup, and walkthrough. Several of them read per-repo JSON preference files from ~/.claude/, which is how you scope behaviour without editing the skill itself.

Installing ryanb/dotfiles and running your first c command

The README gives a three-command install. Clone into ~/.dotfiles, change into it, and run the installer. Because the installer prompts before overwriting, you can run it on a machine that already has some of these files, but you should still read the script first.

git clone [email protected]:ryanb/dotfiles ~/.dotfiles
cd ~/.dotfiles
./bin/install

After the script finishes, the README says to open a new terminal window to see the effects. Nothing takes hold in the shell you ran the installer from.

The first thing to try is the directory shortcut. If your projects live somewhere other than ~/code, set CODE_PATH in .zshrc before you rely on c. The README's example shows two paths, with the base one first.

# in .zshrc
export CODE_PATH="$HOME/code:$HOME/code/railscasts-episodes"

With that in place, typing c followed by a few characters and tab should complete to a project directory. Running c with no argument at all opens fzf, and you select a directory from the list. The h command behaves the same way but searches from your home directory.

If you use Claude Code, the plugin installs through its own commands rather than bin/install. The README lists the marketplace add followed by individual plugin installs.

/plugin marketplace add ryanb/dotfiles
/plugin install bisect@ryanb-dotfiles
/plugin install gfix@ryanb-dotfiles
/plugin install review-queue@ryanb-dotfiles

Several skills accept preferences through JSON files in ~/.claude/. The dependabot-prs skill reads dependabot-prs.json, keyed by owner/repo, so you can limit it to certain labels.

{
  "owner/repo": "Only handle PRs with the javascript label."
}

The standup skill uses a different shape. Only base_path is required; default_branch and preferences are optional. The README notes the skill writes its last-run timestamp to ~/.claude/standup-last-timestamp, so a second run only reports work since the previous one.

Where this configuration stops being the right tool

The README says Mac OS X. It does not claim Linux support, and the top-level entries include macOS-specific terminal configurations for kitty, ghostty, wezterm, and aerospace, a tiling window manager for macOS. If you are on Linux, you are reading someone else's terminal and window manager settings and copying them into a system that does not have those programs. The zshrc and gitconfig portions may transfer, but you are assembling that subset yourself.

The uninstall instructions are the clearest signal of the risk. They are a list of unlink commands for ~/.bin, ~/.gitignore, ~/.gitconfig, ~/.gemrc, ~/.gvimrc, ~/.irbrc, ~/.vim, and ~/.vimrc, followed by rm ~/.zshrc with the comment "careful here", and finally rm -rf ~/.dotfiles. The README warns you to double check the contents before removing so you do not lose custom settings. That warning exists because these are copies, not links with a manager tracking them. Once bin/install writes ~/.zshrc, your previous file is gone unless you saved it.

There is no rollback path documented. The README does not describe a backup step before install, and no restore command appears in the repository listing. If you want to reverse the install, you reconstruct your old configuration from memory or from a backup you made yourself.

The Claude Code plugin is a separate dependency question. It assumes you use Claude Code and that the plugin marketplace commands work in your environment. If you do not, the claude/ directory is inert for you.

Finally, this is one person's configuration for one person's workflow. The c command assumes projects live under a directory you are willing to declare through CODE_PATH. The git prompt assumes you want branch state visible at all times. These are reasonable defaults, but they are defaults someone chose for themselves.

GNU Stow and the difference between copying and linking

The most common alternative approach for this problem is GNU Stow, which appears in the related searches for this topic. The difference is structural. Stow creates symlinks from your home directory into a repository, organized by package directory. Editing a file in your home directory edits the file in the repository, because they are the same file.

ryanb/dotfiles copies. After bin/install runs, ~/.zshrc is a separate file from the zshrc in the repository. If you edit it, your change does not appear in the repository, and if you pull new commits, your local edits are not automatically reconciled. The README acknowledges this by telling you to feel free to customize .zshrc to match your preference, which is advice that only makes sense in a copy-based model.

Neither approach is better in the abstract. Copying is simpler to reason about: there is no link resolution, no risk of a broken symlink, and no dependency on Stow being installed. Linking makes updates and version control cleaner, at the cost of an extra tool and a directory convention you have to maintain. If you want changes to flow back to the repository, Stow is the closer fit. If you want a one-time setup you then edit freely, copying is fine, provided you accept that the uninstall list is your only map of what was written.

A dotfile manager in the broader sense, which several of the related searches point at, adds per-host profiles and templating on top of linking. This repository has none of that. It has an install script and an uninstall list.

Maintenance, licence, and what a fork costs you

The last push to the default branch was on 2026-09-22, so the repository is being touched. That is a statement about commit activity, not about support. There are no releases, so there is no versioned artifact to pin. If you clone, you get whatever master holds at that moment, and updating means pulling and re-running bin/install or copying the files you care about by hand.

The licence is MIT, which is permissive and places few obligations on you. The practical implication for a dotfiles repository is that you can copy individual files into your own configuration without much ceremony. This is not legal advice; read the LICENSE file in the repository root if you need the exact terms.

Upgrade cost is the real ongoing expense, and it is higher than it looks. Because the install copies rather than links, pulling upstream changes does not update your home directory. You either re-run bin/install and answer the overwrite prompts, accepting that your local edits may be replaced, or you diff the repository against your home directory and merge by hand. The README does not document a supported upgrade path, so the second option is what most people will end up doing.

The Claude Code plugin has its own update surface. Plugin installs go through the marketplace commands, and the per-repo JSON preference files in ~/.claude/ are yours, not the repository's, so they survive a plugin update. That separation is a sensible design.

Editorial conclusion

Adopt ryanb/dotfiles if you run Zsh on Mac OS X and want a small, readable configuration you can edit yourself, or if you already use Claude Code and want the twelve bundled skills. Do not adopt it if you are on Linux, if you expect a cross-platform dotfile manager with per-host profiles, or if you want a configuration you never have to read. Before installing, open bin/install and read what it copies, and check whether ~/.zshrc already exists, because the uninstall instructions treat that file differently from the rest.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. ryanb/dotfiles on GitHub