dotfiles

Personal dotfiles for macOS development environment
Primary focus: Claude Code • Cloudflare Workers • Python/Jupyter

Overview

This repository automates the setup of a complete macOS development environment. Run one command on a fresh machine and get a fully configured system in ~15 minutes.

git clone https://github.com/jamesfdavis/dotfiles.git ~/dotfiles && cd ~/dotfiles && ./install.sh

Installation Flow

flowchart TD
    A[🖥️ Fresh macOS] --> B[Clone dotfiles repo]
    B --> C[Run install.sh]
    
    C --> D[1️⃣ Homebrew]
    D --> E[2️⃣ Oh My Zsh]
    E --> F[3️⃣ Symlink Dotfiles]
    F --> G[4️⃣ SSH Keys]
    G --> H[5️⃣ VS Code]
    H --> I[6️⃣ macOS Defaults]
    
    I --> J{Manual Steps}
    J --> K[Register SSH keys on GitHub]
    J --> L[Configure ~/.extra]
    J --> M[Install Node via nvm]
    
    K --> N[✅ Ready to Code]
    L --> N
    M --> N
    
    style A fill:#e03131,color:#fff,stroke:#c92a2a
    style N fill:#2f9e44,color:#fff,stroke:#237032
    style J fill:#f08c00,color:#fff,stroke:#e67700

What Gets Installed

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4c6ef5', 'primaryTextColor': '#fff', 'primaryBorderColor': '#364fc7', 'lineColor': '#868e96', 'secondaryColor': '#ae3ec9', 'tertiaryColor': '#0ca678' }}}%%
mindmap
  root((dotfiles))
    CLI Tools
      git + gh
      ripgrep + fd
      fzf + jq
      bat + eza
    Development
      Node.js via nvm
      Python via uv
      VS Code
    Cloud
      Cloudflare Wrangler
      cloudflared
    Shell
      Oh My Zsh
      zsh-autosuggestions
      zsh-syntax-highlighting
    Security
      SSH Auth Key
      SSH Signing Key

Package Summary

Category	Tools
CLI Essentials	git, gh, jq, yq, ripgrep, fzf, bat, eza, fd, tree, htop
Node.js	nvm (then `nvm install --lts`)
Python	uv, python@3.12
Cloud/Deploy	wrangler, cloudflared
Shell	zsh-autosuggestions, zsh-syntax-highlighting
Apps	iTerm2, VS Code, Claude
Fonts	Fira Code Nerd Font

SSH Key Architecture

This setup uses two separate SSH keys for security isolation:

flowchart LR
    subgraph Your Machine
        A[Auth Key<br/>~/.ssh/id_ed25519]
        S[Signing Key<br/>~/.ssh/id_ed25519_signing]
    end
    
    subgraph GitHub
        GA[Authentication Key<br/>Push/Pull Access]
        GS[Signing Key<br/>Commit Verification]
    end
    
    A -->|Registered as| GA
    S -->|Registered as| GS
    
    GA -->|Enables| P[git push/pull]
    GS -->|Enables| V[✓ Verified Badge]
    
    style A fill:#1c7ed6,color:#fff,stroke:#1864ab
    style S fill:#d6336c,color:#fff,stroke:#a61e4d
    style V fill:#2f9e44,color:#fff,stroke:#237032
    style GA fill:#495057,color:#fff,stroke:#343a40
    style GS fill:#495057,color:#fff,stroke:#343a40
    style P fill:#495057,color:#fff,stroke:#343a40

Why two keys?

Auth key compromised? Commit history stays verified
Rotate signing key? Don't lose SSH access
Different security contexts, different keys

📖 Full documentation: docs/KEYS.md

File Structure

dotfiles/
├── install.sh                 # 🚀 Main entry point
├── bootstrap.sh               # Symlinks dotfiles to ~
├── Brewfile                   # Homebrew packages
│
├── scripts/
│   ├── setup-homebrew.sh      # Installs Homebrew + bundle
│   ├── setup-oh-my-zsh.sh     # Installs OMZ + plugins
│   ├── setup-ssh-signing.sh   # Generates signing key
│   └── setup-vscode.sh        # Configures VS Code
│
├── vscode/
│   ├── settings.json          # Editor preferences
│   ├── keybindings.json       # Custom shortcuts
│   └── extensions.txt         # Extension list
│
├── docs/
│   └── KEYS.md                # SSH key documentation
│
├── .zshrc                     # Shell configuration
├── .aliases                   # Command shortcuts
├── .exports                   # Environment variables
├── .functions                 # Shell functions
├── .gitconfig                 # Git settings + signing
├── .gitignore                 # Global ignores
├── .extra.example             # Template for secrets
│
└── ... (other dotfiles)

Post-Installation Steps

After install.sh completes, you'll need to:

sequenceDiagram
    participant You
    participant Terminal
    participant GitHub
    participant VSCode
    
    Note over You,VSCode: Installation Complete ✓
    
    You->>Terminal: source ~/.zshrc
    You->>Terminal: nvm install --lts
    
    You->>Terminal: cat ~/.ssh/id_ed25519.pub
    You->>GitHub: Add as "Authentication Key"
    
    You->>Terminal: cat ~/.ssh/id_ed25519_signing.pub
    You->>GitHub: Add as "Signing Key"
    
    You->>Terminal: cp ~/.extra.example ~/.extra
    You->>Terminal: Edit with API keys
    
    You->>VSCode: Disable Settings Sync
    
    Note over You,VSCode: Ready to Code! 🎉

Quick Checklist

Restart terminal or source ~/.zshrc
Install Node: nvm install --lts
Add auth key to GitHub: cat ~/.ssh/id_ed25519.pub
Add signing key to GitHub: cat ~/.ssh/id_ed25519_signing.pub
Configure secrets: cp ~/.extra.example ~/.extra && code ~/.extra
Disable VS Code Settings Sync

Daily Usage

Key Aliases

# ─────────────────────────────────────────────
# Claude Code
# ─────────────────────────────────────────────
cc          # claude
ccc         # claude chat
ccr         # claude --resume

# ─────────────────────────────────────────────
# Cloudflare Wrangler
# ─────────────────────────────────────────────
wr          # wrangler
wrd         # wrangler dev
wrp         # wrangler deploy
wrd1        # wrangler d1

# ─────────────────────────────────────────────
# Git (common)
# ─────────────────────────────────────────────
gs          # git status
ga          # git add
gc          # git commit
gp          # git push
gl          # git pull
gco         # git checkout
gcob        # git checkout -b
glog        # git log --oneline --graph

# ─────────────────────────────────────────────
# GitHub CLI
# ─────────────────────────────────────────────
ghpr        # gh pr create
ghprw       # gh pr view --web
ghprc       # gh pr checkout

# ─────────────────────────────────────────────
# Python (uv)
# ─────────────────────────────────────────────
uvv         # uv venv
uva         # source .venv/bin/activate
uvi         # uv pip install

See .aliases for the complete list.

Updating Dotfiles

Changes to symlinked files take effect immediately. To pull updates from the repo:

cd ~/dotfiles
git pull
source ~/.zshrc  # Reload shell config

Adding New Packages

# Edit Brewfile
code ~/dotfiles/Brewfile

# Install new packages
brew bundle --file=~/dotfiles/Brewfile

Customization

Personal Configuration (~/.extra)

Store sensitive data and machine-specific config in ~/.extra (not committed):

# Git identity
GIT_AUTHOR_NAME="James Davis"
GIT_AUTHOR_EMAIL="ragingsmurf@gmail.com"
git config --global user.name "$GIT_AUTHOR_NAME"
git config --global user.email "$GIT_AUTHOR_EMAIL"

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ACCOUNT_ID="..."

# Work mode (enables work-specific aliases)
export WORK_HOST="true"

VS Code

Settings are managed via dotfiles, not VS Code's built-in sync:

~/dotfiles/vscode/settings.json    →  symlinked to VS Code
~/dotfiles/vscode/keybindings.json →  symlinked to VS Code
~/dotfiles/vscode/extensions.txt   →  installed via script

To add extensions: Edit vscode/extensions.txt and run ./scripts/setup-vscode.sh

Workflow Diagram

flowchart TB
    subgraph Development
        CC[Claude Code<br/>cc]
        VS[VS Code<br/>code .]
        GH[GitHub CLI<br/>gh]
    end
    
    subgraph Deployment
        WR[Wrangler<br/>wr]
        CF[Cloudflare Workers]
    end
    
    subgraph Local Environment
        ZSH[ZSH + Oh My Zsh]
        NVM[Node via nvm]
        UV[Python via uv]
    end
    
    CC --> VS
    VS --> GH
    GH -->|Signed Commits| CF
    WR --> CF
    
    ZSH --> CC
    ZSH --> VS
    NVM --> WR
    UV --> CC
    
    style CC fill:#7c3aed,color:#fff,stroke:#6d28d9
    style VS fill:#1c7ed6,color:#fff,stroke:#1864ab
    style GH fill:#495057,color:#fff,stroke:#343a40
    style WR fill:#f76707,color:#fff,stroke:#d9480f
    style CF fill:#f76707,color:#fff,stroke:#d9480f
    style ZSH fill:#2f9e44,color:#fff,stroke:#237032
    style NVM fill:#2f9e44,color:#fff,stroke:#237032
    style UV fill:#2f9e44,color:#fff,stroke:#237032

Troubleshooting

Shell not loading config

source ~/.zshrc

Homebrew commands not found (Apple Silicon)

eval "$(/opt/homebrew/bin/brew shellenv)"

Git commits not showing "Verified"

Ensure signing key is uploaded as Signing Key (not Auth)
Verify email matches: git config --global user.email
Check signing is enabled: git config --global commit.gpgsign

VS Code settings not applying

# Re-run VS Code setup
./scripts/setup-vscode.sh

# Verify symlinks
ls -la ~/Library/Application\ Support/Code/User/

NVM not working

# NVM is lazy-loaded. First call initializes it:
nvm --version

Maintenance

Updating Everything

# Update Homebrew packages
brewup  # alias for: brew update && brew upgrade && brew cleanup

# Update dotfiles
cd ~/dotfiles && git pull && source ~/.zshrc

# Update Oh My Zsh
omz update

Backing Up Keys

Store these securely (1Password, encrypted USB):

~/.ssh/id_ed25519 (auth private key)
~/.ssh/id_ed25519_signing (signing private key)

Credits

Originally forked from mathiasbynens/dotfiles.

Refactored January 2026 for Claude Code + Cloudflare development workflow.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 278 Commits
docs		docs
init		init
scripts		scripts
setup		setup
vscode		vscode
.aliases		.aliases
.curlrc		.curlrc
.editorconfig		.editorconfig
.exports		.exports
.extra.example		.extra.example
.functions		.functions
.git_commit.txt		.git_commit.txt
.gitattributes		.gitattributes
.gitconfig		.gitconfig
.gitignore		.gitignore
.gvimrc		.gvimrc
.hushlogin		.hushlogin
.inputrc		.inputrc
.osx		.osx
.screenrc		.screenrc
.tmux.conf		.tmux.conf
.vimrc		.vimrc
.wgetrc		.wgetrc
.zshrc		.zshrc
Brewfile		Brewfile
LICENSE-MIT.txt		LICENSE-MIT.txt
README.md		README.md
bootstrap.sh		bootstrap.sh
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

dotfiles

Overview

Installation Flow

What Gets Installed

Package Summary

SSH Key Architecture

File Structure

Post-Installation Steps

Quick Checklist

Daily Usage

Key Aliases

Updating Dotfiles

Adding New Packages

Customization

Personal Configuration (~/.extra)

VS Code

Workflow Diagram

Troubleshooting

Shell not loading config

Homebrew commands not found (Apple Silicon)

Git commits not showing "Verified"

VS Code settings not applying

NVM not working

Maintenance

Updating Everything

Backing Up Keys

Credits

License

About

Uh oh!

Releases

Packages

Contributors 2

Uh oh!

Languages

License

jamesfdavis/dotfiles

Folders and files

Latest commit

History

Repository files navigation

dotfiles

Overview

Installation Flow

What Gets Installed

Package Summary

SSH Key Architecture

File Structure

Post-Installation Steps

Quick Checklist

Daily Usage

Key Aliases

Updating Dotfiles

Adding New Packages

Customization

Personal Configuration (~/.extra)

VS Code

Workflow Diagram

Troubleshooting

Shell not loading config

Homebrew commands not found (Apple Silicon)

Git commits not showing "Verified"

VS Code settings not applying

NVM not working

Maintenance

Updating Everything

Backing Up Keys

Credits

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages