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]"
:::callout
The documentation for httpie calls for install with pip, but on
macOS there is an OpenSSL issue. Install with uv tool (which uses a Python installation it manages), not
system Python:
/Users/iancleary/.local/share/uv/tools/httpie/lib/python3.9/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 2.8.3'.
Again, when using uv tool, this issue goes away, since we are not using the system python installation.
::
Go tools
::tip
target: _blank to: https://go.dev/doc/install
Learn how to install go!
::
go install github.com/jesseduffield/lazygit@latest
fzf
::tip
target: _blank to: https://github.com/junegunn/fzf
fzf is a general-purpose command-line fuzzy finder. ::
# 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"
}
::tip
target: _blank to: https://github.com/junegunn/fzf/wiki/examples
See the fzf wiki for many more examples and integrations. ::
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
::tip
target: _blank to: https://chatgpt.com/codex
Learn how to install OpenAI's CLI, codex!
::
Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash
::tip
target: _blank to: https://claude.ai/settings/claude-code
Learn how to install Claude Code's CLI, claude!
::
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.
::tip
target: _blank to: https://docs.anthropic.com/en/docs/claude-code/skills
Learn more about Claude Skills in the official documentation. ::
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.
::tip
target: _blank to: https://pica.joshpuckett.me/
Pica — macOS font management app by Josh Puckett. ::
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.
::tip
target: _blank to: https://ghostty.org/docs/config
See Ghostty configuration examples and docs. ::
MacPorts
::tip
target: _blank to: https://guide.macports.org/#installing
MacPorts is an easy system for compiling, installing, and managing open source software. ::
Visual Studio Code
https://code.visualstudio.com/download
::tip
target: _blank to: https://stackoverflow.com/a/33303456
Open VS Code with command-line arguments:
code () { VSCODE_CWD="$PWD" open -n -b "com.microsoft.VSCode" --args $* ;}
For example, code . opens the current directory.
::
Google Antigravity
::tip
target: _blank to: https://antigravity.google
VSCode fork with Google AI tools. ::
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/parabola/spline/parabola primitives. Its UI is highly customizable.
3D Modeling
ZSH Configuration
::tip
target: _blank to: /rfd/0003
Learn how to install and wire in performant Mac CLI tools. ::
.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.
::tip This guide is for a Python version you installed manually (typically from python.org), not the system Python. Removing system Python can break Apple tooling. ::
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
::tip
target: _blank to: https://x.com/minchoi/status/2000951667416875081
Original reference on macOS image to 3D model conversion. ::
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.
::tip
target: _blank to: https://oskargroth.com/blog/reverse-engineering-nsvisualeffectview
Oskar Groth — Reverse Engineering NSVisualEffectView (full deep dive) ::
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"
::callout
Running nice -n -20 requires root privileges. If you're logging in as a non-root user, use
sudo nice -n -20 bash instead.
::
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