Overview
Welcome to the macOS section of the documentation.
Here, you'll find a curated list of applications, keyboard shortcuts, and workflows designed to enhance your productivity and streamline your experience on the macOS operating system.
Whether you are a developer, designer, or everyday user, these resources will help you make the most out of macOS.
For GitHub SSH-specific configuration, agent reliability, and host-scoped ~/.ssh/config guidance, see 0005.
Command Line Interface
Tools I recommend you install on macOS.
| Tool | Purpose | Example |
|---|---|---|
| Powerlevel 10k | Zsh theme for speed and flexibility | p10k configure |
| nvm | Node Version Manager | nvm install stable |
| node | JavaScript runtime | node --version |
| npm | Node package manager | npm install -g pnpm |
| pnpm | Disk space efficient package manager | pnpm --version |
| bun | Fast all-in-one JavaScript runtime | bun --version |
| rustup | Rust toolchain installer | rustup default stable && rustup update |
| cargo | Rust package manager | cargo install just |
| just | Command runner | just |
| eza | Modern replacement for ls | eza |
| fd | Simple, fast alternative to find | fd pattern |
| ripgrep | Fast alternative to grep | rg pattern |
| ast-grep | Structural search and replace | ast-grep |
| bat | cat clone with syntax highlighting | bat file.txt |
| zoxide | Smarter cd command | z directory |
| git-delta | Syntax-highlighting pager for git | delta |
| uv | Fast Python package manager | uv tool install httpie |
| pre-commit | Git hook management framework | pre-commit install |
| httpie | Modern command-line HTTP client | http GET example.com |
| yt-dlp | A feature-rich command-line audio/video downloader | yt-dlp "example.com" |
| lazygit | Terminal UI for git | lazygit |
| fzf | Command-line fuzzy finder | fzf |
| jq | Command-line JSON processor | jq . |
Terminal and Shell Setup
Powerlevel 10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc
Manual Font Setup
- Download these four ttf files:
- Double-click on each file and click "Install" to add it to your system.
- Configure terminal font usage (iTerm2, Terminal, Hyper, VS Code, Ghostty).
Node Version Manager: Node, NPM, and Bun
nvm on
nvm install stable
nvm use stable
node --version
npm --version
npm # to see if there is a version to upgrade to
npm install -g bun
# npm install -g bun@1.2.4 # (to upgrade or use a specific version of `bun`)
npm install -g pnpm
# npm install -g pnpm@9.0.0 # (to upgrade or use a specific version of `pnpm`)
bun --version
pnpm --version
Rust
rustup default stable
rustup update
Rust Tools
cargo install just --locked
cargo install eza --locked
cargo install fd-find --locked
cargo install ripgrep --locked
cargo install ast-grep --locked
cargo install bat --locked
cargo install zoxide --locked
cargo install git-delta --locked
cargo install typst-cli --locked
Python
Python tools
uv tool install --python 3.14 pre-commit --with pre-commit-uv
uv tool install --python 3.14 httpie
uv tool install --python 3.14 "yt-dlp[default]"
Go tools
go install github.com/jesseduffield/lazygit@latest
fzf
# Find files interactively
fzf
# Preview files with bat
fzf --preview 'bat --color=always {}'
# Use fd as the default source (respects .gitignore)
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'
# Search file contents with ripgrep, then open in editor
rg --line-number . | fzf --delimiter ':' --preview 'bat --color=always --highlight-line {2} {1}'
# Find directories with fd
fd --type d | fzf
# Fuzzy cd into a directory
fcd() {
local dir
dir=$(fd --type d | fzf --preview 'eza --tree --level=1 {}') && cd "$dir"
}
# Fuzzy search command history
fhist() {
local cmd
cmd=$(history -1 0 | fzf --tac | sed 's/^ *[0-9]* *//')
print -z "$cmd"
}
# Fuzzy checkout git branch
fbr() {
local branch
branch=$(git branch --all | grep -v HEAD | fzf --preview 'git log --oneline --graph -10 {}' | sed 's/.* //' | sed 's|remotes/origin/||')
git checkout "$branch"
}
MacPorts
sudo port install fzf
sudo port install jq
Dotfiles
I manage my shell configuration with a dotfiles repo that syncs across machines. On macOS, this covers zsh configs, Powerlevel10k, shared aliases, and AI agent configuration.
git clone git@github.com:iancleary/dotfiles.git ~/dotfiles
cd ~/dotfiles
./sync-dotfiles.sh push # Install configs from repo
./sync-dotfiles.sh pull # Backup current configs to repo
./sync-dotfiles.sh status # Check for differences
The sync utility detects the OS and installs the appropriate files: zsh configs on macOS/Linux and bash configs on Windows. Shared utilities are installed on all platforms.
What Gets Synced (macOS)
.zshrc,.zshenv,.zprofileโ Zsh configuration with Powerlevel10k.p10k.zshโ Powerlevel10k theme configuration.common/aliases.shโ Shell aliases (eza, git, docker, cargo, just).common/agents-git-trees.shโ Git worktree helpers (ga/gd).claude/โ Claude Code settings, skills, principles.codex/โ Codex CLI rules and MCP servers
AI Tools
OpenAI Codex CLI
npm i -g @openai/codex
Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash
Claude Browser Dev
Claude Code can use a local browser for development preview, allowing it to visually verify changes and interact with your running application.
claude --browser
Claude Skills
Claude Skills let you teach Claude Code reusable capabilities. Create a .claude/skills/ directory with
SKILL.md files that describe how to perform specific tasks.
mkdir -p .claude/skills
touch .claude/skills/SKILL.md
Applications and Productivity
Pica
Pica is a native, free macOS font management app with logo previews, color themes, full OpenType support, custom collections, one-click activation, and watch folders.
Ghostty
Ghostty is a fast, feature-rich, cross-platform terminal emulator.
window-padding-x = 8
window-padding-y = 0,4
The window-padding-y = 0,4 sets 0 padding on top and 4 at the bottom for cleaner vertical balance.
MacPorts
Visual Studio Code
https://code.visualstudio.com/download
Google Antigravity
GitHub Desktop
https://desktop.github.com/download/
LibreCAD 2D CAD Editor
LibreCAD is a cross-platform 2D CAD program written in C++17. It can read DXF/DWG files and can write DXF/PDF/SVG files. It supports point/line/circle/ellipse/spline/parabola primitives. Its UI is highly customizable.
3D Modeling
ZSH Configuration
.zshrc
Here is my .zshrc file at the time of writing this.
autoload -Uz compinit
compinit
# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n]
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi
source ~/powerlevel10k/powerlevel10k.zsh-theme
# Load git shortcuts, 1> file redirects stdout to file
[[ ! -f ~/.zsh/git.zsh ]] || source ~/.zsh/git.zsh 1>/dev/null
[[ ! -f ~/.zsh/aliases.zsh ]] || source ~/.zsh/aliases.zsh 1>/dev/null
[[ ! -f ~/.zsh/vscode.zsh ]] || source ~/.zsh/vscode.zsh 1>/dev/null
# load nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
# load rustup and cargo
[[ ! -f ~/.cargo/env ]] || source "$HOME/.cargo/env" 1>/dev/null
[[ ! -f ~/.cargo/bin/just ]] || alias j=just 1>/dev/null
[[ ! -f ~/.cargo/bin/bat ]] || alias cat=bat 1>/dev/null
[[ ! -f ~/.cargo/bin/rg ]] || alias grep=rg 1>/dev/null
[[ ! -f ~/.cargo/bin/zoxide ]] || eval "$(zoxide init zsh)" 1>/dev/null
# https://github.com/dandavison/delta?tab=readme-ov-file#get-started
[[ ! -f ~/.cargo/bin/delta ]] || git config --global core.pager delta 1>/dev/null
[[ ! -f ~/.cargo/bin/delta ]] || git config --global interactive.diffFilter 'delta --color-only' 1>/dev/null
[[ ! -f ~/.cargo/bin/delta ]] || git config --global delta.navigate true 1>/dev/null
[[ ! -f ~/.cargo/bin/delta ]] || git config --global merge.conflictStyle zdiff3 1>/dev/null
[[ ! -f ~/.cargo/bin/delta ]] || export DELTA_FEATURES=+side-by-side 1>/dev/null
# load uv (python)
[[ ! -f ~/.local/bin/env ]] || source "$HOME/.local/bin/env" 1>/dev/null
# Add go bin to path (if ~/go/bin directory exists)
[[ -d ~/go/bin ]] && export PATH="$HOME/go/bin:${PATH}" 1>/dev/null
alias lg='lazygit'
# Set up fzf key bindings and fuzzy completion
[[ ! -f /opt/local/share/fzf/shell/completion.zsh ]] || source /opt/local/share/fzf/shell/completion.zsh 1>/dev/null
[[ ! -f /opt/local/share/fzf/shell/key-bindings.zsh ]] || source /opt/local/share/fzf/shell/key-bindings.zsh 1>/dev/null
[[ ! -f ~/.zsh/fzf.zsh ]] || source ~/.zsh/fzf.zsh 1>/dev/null
# load python (for pre-commit)
[[ ! -f /Library/Frameworks/Python.framework/Versions/Current/Bin ]] || PATH="/Library/Frameworks/Python.framework/Versions/Current/Bin:${PATH}" 1>/dev/null
alias pip=pip3
alias python=python3
# Load ssh keys
[[ ! -f ~/.ssh/github_id_ed25519 ]] || eval "$(ssh-agent -s)" 1>/dev/null && ssh-add ~/.ssh/github_id_ed25519 2>/dev/null
# Added by Antigravity (edited by me to handle folder not existing)
[[ -d "$HOME/.antigravity/antigravity/bin" ]] && export PATH="$HOME/.antigravity/antigravity/bin:$PATH"
# pnpm
export PNPM_HOME="/Users/iancleary/Library/pnpm"
case ":$PATH:" in
*":$PNPM_HOME:"*) ;;
*) export PATH="$PNPM_HOME:$PATH" ;;
esac
### ---- DO NOT PUT ANYTHING BELOW THIS LINE ---- ###
# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh.
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh
### ---- DO NOT PUT ANYTHING HERE ---- ###
Uninstall Python
To uninstall the specific Python version located at
/Library/Frameworks/Python.framework/Versions/3.14/bin/python3, use the Terminal to remove the framework and
symlinks.
Step 1: Remove the Python Framework
sudo rm -rf /Library/Frameworks/Python.framework/Versions/3.14
Step 2: Remove the Python Application
- Open Finder and go to Applications.
- Move any Python 3.14 application to the Trash.
- Right-click Trash and choose Empty Trash.
Step 3: Remove Symbolic Links
cd /usr/local/bin
ls -l | grep '/Library/Frameworks/Python.framework/Versions/3.14'
ls -l | grep '/Library/Frameworks/Python.framework/Versions/3.14' | awk '{print $9}' | xargs sudo rm -f
Step 4: Validate the Uninstallation
which python3
python3.14 --version
Image to 3D Model on macOS
Apple's SHARP technology can convert 2D images into 3D models directly on macOS.
- Takes one or more 2D images as input
- Generates 3D models with texture
- Runs on Apple Silicon using the Neural Engine
- Useful for AR/VR content creation, game assets, and prototyping
NSVisualEffectView and Material Effects
macOS uses NSVisualEffectView for blur and vibrancy effects throughout the system UI.
Layer Stack
NSVisualEffectView.layer
โโ container (CALayer)
โโ backdrop (CABackdropLayer) โ samples content behind
โโ tint (CALayer) โ color overlay with blend mode
CABackdropLayer is a private Core Animation class that samples content behind the view and applies filters.
The tint layer blends color on top to create the material appearance.
Key Insights
- Built-in materials are pre-defined configurations loaded from CoreUI.
- Control Center uses custom materials not exposed via
NSVisualEffectView.Material. - Material behavior is often reimplemented manually to match system look.
- Materials are structured in CoreUI asset catalogs.
SSH: Priority Login Under Heavy Load
When a server is under heavy load, new SSH sessions can be slow or time out. Use nice to get a higher
priority shell immediately:
ssh -o ConnectTimeout=1 -o ConnectionAttempts=1 user@host "nice -n -20 bash"
Mac Mini Server Setup
Prevent Sleep
sudo pmset -a sleep 0 displaysleep 0 disksleep 0
sleep 0โ never sleep the systemdisplaysleep 0โ never sleep the displaydisksleep 0โ never sleep the disk
Auto-Restart After Power Failure
sudo pmset -a autorestart 1
Verify Settings
pmset -g
Auto-Login
System Settings โ Users & Groups โ Automatic Login โ select account.
Remote Access
Enable SSH under System Settings โ General โ Sharing โ Remote Login, then connect with:
ssh username@hostname