macOS Dotfiles + Claude Code Config

macOS dotfiles managed with GNU Stow. Most of it is my Claude Code setup — CLAUDE.md, settings.json, custom skills, and subagents — plus the usual zsh, Brewfile, and macOS defaults.

What is tracked

• claude/ for Claude Code global configuration (CLAUDE.md, settings.json, statusline.sh, skills/, agents/)
• codex/ for Codex CLI configuration (AGENTS.md — the shared global guidelines, which Claude's CLAUDE.md imports)
• zsh/ for shell configuration
• git/ for the global git config (.gitconfig)
• vscode/ keeps the last VS Code settings for reference; VS Code is uninstalled and install.sh doesn't stow it
• Brewfile for package reproducibility
• macos-defaults.sh for common macOS preferences

Machine-specific secrets stay outside the repo:

• ~/.zshrc.local

Prerequisites

Required:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install stow

Optional but recommended:

brew bundle --file Brewfile

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

The shell config is defensive now, so missing optional tools will not break shell startup.

Install

./install.sh
source ~/.zshrc

What install.sh does:

• stows tracked packages into $HOME
• detects recursive conflicts before linking
• backs up replaced files to ~/.dotfiles-backups/<timestamp>/
• creates ~/.zshrc.local when missing

Restore packages

Install packages from the tracked Homebrew bundle:

brew bundle --file Brewfile

Apply macOS preferences

Review the script first, then run it manually if you want those defaults:

chmod +x macos-defaults.sh
./macos-defaults.sh

Local-only files

Example ~/.zshrc.local:

export GITHUB_TOKEN="your_token_here"
export OPENAI_API_KEY="your_key_here"

Structure

dotfiles/
├── Brewfile
├── CLAUDE.md          # editing notes for coding agents working on this repo
├── LICENSE
├── claude/
│   └── .claude/
│       ├── CLAUDE.md            # imports ~/.codex/AGENTS.md + Claude-only delegation section
│       ├── settings.json
│       ├── statusline.sh        # custom 2-line status line (context + rate-limit gauges)
│       ├── agents/
│       │   ├── aesthetic-critic.md   # taste/craft critique of already-captured UI screenshots
│       │   └── usability-critic.md   # task-scenario usability critique (drives the browser itself)
│       └── skills/
│           ├── codex-image/          # codex image_generation skill (single/batch/parallel)
│           ├── korean-polish/        # writes and polishes Korean the user posts so it reads human (rules.md; projects add their own)
│           └── visual-review/        # Playwright MCP rendering critique (reads per-repo visual-review-app companion)
├── codex/
│   └── .codex/
│       └── AGENTS.md  # shared global guidelines (Codex reads it directly, Claude imports it)
├── docs/
│   └── claude-code.md # what Claude Code writes into this repo, and what to do with it
├── git/
│   └── .gitconfig
├── install.sh
├── macos-defaults.sh
├── vscode/            # archived VS Code settings (not stowed)
│   ├── keybindings.json
│   └── settings.json
├── zsh/
│   ├── .zshrc
│   └── .zshrc.local.example
└── README.md