Personal configuration for a productive shell and editor setup on macOS and Linux (Arch, Debian). Install scripts link configs from this repo into your home directory so you can version everything in git and reproduce the same environment on a new machine.

Inspired by Mathias Bynens’s dotfiles. More background on the dotfiles idea: dotfiles.github.io.

• Quick start (macOS)
• Quick start (Linux)
• What’s included
• AI, Cursor, and Claude Code
• Environment variables
• Installation
  • What install.sh does
• Optional: more software
• Repository layout
• Feedback & thanks

mkdir -p ~/GitHub && cd ~/GitHub
git clone https://github.com/mingster/dotfiles.git && cd dotfiles

sh mac/osxprep.sh          # Command Line Tools + prep
sh mac/osx.sh              # Optional: macOS defaults (review first)
sh install.sh              # Symlinks, .agents, Cursor, Claude Code; runs mac/system_setup.sh

Each run of **install.sh** (bash script, runnable as sh install.sh or bash install.sh):

1. Sets **~/dotfiles** to a symlink → the absolute path of the directory that contains install.sh (re-running from another clone retargets ~/dotfiles).
2. Refreshes home links for git, vim, **.agents**, Claude Code (script/setup-claude-code.sh → ~/.claude/), and Cursor (rules + user settings via script/link-cursor-user.sh).

If **~/dotfiles exists as a real directory** (not a symlink), the script exits with an error so nothing is overwritten blindly.

Same clone location as macOS. **install.sh** sets up home symlinks (including **.agents**, Claude Code via script/setup-claude-code.sh, Cursor via script/link-cursor-user.sh), then runs the right **system_setup** for the machine:

Unsupported distros print a message but still keep the symlinks from earlier in the script. To only link dotfiles and skip the heavy installer (testing, unsupported distro), use **DOTFILES_SKIP_SYSTEM_SETUP=1**.

mkdir -p ~/GitHub && cd ~/GitHub
git clone https://github.com/mingster/dotfiles.git && cd dotfiles

sh install.sh                       # symlinks + platform system_setup

Requirements: **bash**, **git**, and **sudo** where the platform script installs packages. Read **arch/system_setup.sh** or **debian/system_setup.sh** before running on a machine you care about. They are full environment installers.

On Windows (Git Bash / MSYS), **install.sh** still runs the symlink block when **$HOME/dotfiles** resolves; **system_setup** is skipped and Cursor user linking may not apply (see script/link-cursor-user.sh).

Dotfiles wires skills (skills CLI), Claude Code, and Cursor (global rules + user settings.json / keybindings.json) into your home directory.

Examples:

DOTFILES_INSTALL_SKILLS=1 sh ~/GitHub/dotfiles/install.sh
DOTFILES_BREW_UPGRADE=1 sh ~/GitHub/dotfiles/install.sh

mkdir -p ~/GitHub && cd ~/GitHub
git clone https://github.com/mingster/dotfiles.git && cd dotfiles

From the repo root (or use absolute paths):

sh install.sh

This ensures **~/dotfiles** → this repo, links shell/git/vim dotfiles (overwriting previous symlinks), sets up **.agents**, Claude Code (script/setup-claude-code.sh), Cursor rules + user settings, and optional skills when **DOTFILES_INSTALL_SKILLS=1**. It then runs the platform **system_setup** detected from **OSTYPE** and **/etc/os-release** on Linux (see Quick start (Linux)), unless **DOTFILES_SKIP_SYSTEM_SETUP=1**.

Order of operations (see source in [install.sh](install.sh)):

1. **~/dotfiles** → symlink to this repo (fails if **~/dotfiles** exists and is not a symlink).
2. Home symlinks (targets under the repo): .csvignore, .editorconfig, .gitattributes, .gitflow_export, .gitignore, .gitignore_global, .hgignore_global, .nanorc, .vimrc, .vim.
3. **~/.gitconfig** copied from .gitconfig (arm64) or .gitconfig-x64 (x86_64).
4. **git config --global** core.excludesfile and core.attributesfile pointing at files in this repo.
5. **mkdir -p ~/dotfiles/.agents**, **~/.agents** → **~/dotfiles/.agents**.
6. **bash script/setup-claude-code.sh**: **~/.claude/** ← symlinks into **.agents/skills**, **.agents/claude/**, and **.agents/claude/agents/**.
7. **~/.cursor/rules** → **~/dotfiles/cursor/rules**.
8. If **DOTFILES_INSTALL_SKILLS=1**: **bash script/bootstrap-agents.sh**.
9. **bash script/link-cursor-user.sh**: Cursor User **settings.json** and **keybindings.json** → **~/dotfiles/cursor/** (macOS and Linux paths only).
10. Unless **DOTFILES_SKIP_SYSTEM_SETUP=1**, run **mac/system_setup.sh**, **arch/system_setup.sh**, or **debian/system_setup.sh** as detected.

Platform **system_setup** scripts also call **bash script/setup-claude-code.sh** (and other links) so a manual re-run of **system_setup** stays aligned.

Symlink loop (Too many levels of symbolic links): install.sh uses the physical repo path (pwd -P) so ~/dotfiles and paths like ~/dotfiles/mac/system_setup.sh do not walk a circular symlink chain. If you still see this error, remove the broken symlink rm ~/dotfiles (only if it is a symlink, not a real folder), then run install.sh again from your clone (for example cd ~/GitHub/dotfiles && sh install.sh). Do not point two locations at each other (for example ~/dotfiles → ~/GitHub/dotfiles and ~/GitHub/dotfiles → ~/dotfiles).

Duplicate skills in Cursor: Cursor loads global skills from both ~/.cursor/skills/ and ~/.claude/skills/. If both point at the same tree, every skill appears twice. script/setup-claude-code.sh removes a redundant ~/.cursor/skills when it matches ~/.claude/skills (re-run install.sh or that script). See .agents/README.md.

sh ~/GitHub/dotfiles/mac/osxprep.sh

Run before or after install.sh depending on whether you need CLT first; adjust to your workflow.

Review mac/osx.sh, then:

sh ~/GitHub/dotfiles/mac/osx.sh

Review and edit first. Installs many CLI and GUI packages:

sh ~/GitHub/dotfiles/mac/install_my_software.sh

install.sh already invokes **arch/system_setup.sh** or **debian/system_setup.sh** when **/etc/os-release** matches (see Quick start (Linux)). To run a script again manually (for example after editing it):

cd ~/GitHub/dotfiles
bash arch/system_setup.sh    # or debian/system_setup.sh

Read the script first: both install packages, change the default shell to fish, configure UFW and desktop tooling, etc.

• macOS: mac/install_*.sh — Android, AWS, databases, Python, Node, nginx, etc.
• Linux (Arch): arch/install_*.sh — Node, Java, PostgreSQL, MongoDB, NVIDIA, KDE, Claude Code (arch/install_claude.sh), Zed (arch/install_zed.sh), and others.
• Linux (Debian): debian/install_*.sh — TeX, Zotero, Mullvad, singularity, VNC, etc.
• Editors (all): vscode/vscode_README.md, vscode/install-vscode-extensions.sh, cursor/install-vscode-extensions_cursor.sh

Suggestions and improvements are welcome.

Thanks to josean-dev / dev-environment-files, Sketchybar setup (josean.com), @ptb’s Mac OS X Lion Setup, Ben Alman, Chris Gerke / Insta, Cãtãlin Mariş, Gianni Chiappini / gf3, Jan Moesen / tilde, Lauri Ranta / OS X notes, Matijs Brinkhuis, Nicolas Gallagher, Sindre Sorhus, Tom Ryder, Kevin Suttle / OSXDefaults, Haralan Dobrev, and everyone who contributed or suggested improvements.