RFD 0003Document view
Catalog
RFD 0003
publishedmdx0003.mdx

macOS Workflows and Setup

Consolidated macOS references for applications, command line tooling, terminal setup, and system workflows.

Authors
Ian Cleary
Updated
Apr 21, 2026, 12:00 AM

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.

ToolPurposeExample
Powerlevel 10kZsh theme for speed and flexibilityp10k configure
nvmNode Version Managernvm install stable
nodeJavaScript runtimenode --version
npmNode package managernpm install -g pnpm
pnpmDisk space efficient package managerpnpm --version
bunFast all-in-one JavaScript runtimebun --version
rustupRust toolchain installerrustup default stable && rustup update
cargoRust package managercargo install just
justCommand runnerjust
ezaModern replacement for lseza
fdSimple, fast alternative to findfd pattern
ripgrepFast alternative to greprg pattern
ast-grepStructural search and replaceast-grep
batcat clone with syntax highlightingbat file.txt
zoxideSmarter cd commandz directory
git-deltaSyntax-highlighting pager for gitdelta
uvFast Python package manageruv tool install httpie
pre-commitGit hook management frameworkpre-commit install
httpieModern command-line HTTP clienthttp GET example.com
yt-dlpA feature-rich command-line audio/video downloaderyt-dlp "example.com"
lazygitTerminal UI for gitlazygit
fzfCommand-line fuzzy finderfzf
jqCommand-line JSON processorjq .

Terminal and Shell Setup

Powerlevel 10k

Tip

Powerlevel10k is a theme for Zsh. It emphasizes speed, flexibility and out-of-the-box experience.

BASH
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc
Tip

Fonts can be downloaded and installed via this tip's link.

Manual Font Setup

  1. Download these four ttf files:
  2. Double-click on each file and click "Install" to add it to your system.
  3. Configure terminal font usage (iTerm2, Terminal, Hyper, VS Code, Ghostty).

Node Version Manager: Node, NPM, and Bun

Tip

Learn how to install node with nvm.

BASH
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

Tip

Learn how to install the rustup utility and the cargo package manager!

BASH
rustup default stable
rustup update

Rust Tools

BASH
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

Callout

My recommendation for new Python projects is to use uv package manager, which is an extremely fast Python package and project manager, written in Rust.

Tip

Learn how to install the uv package manager!

Python tools

BASH
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:

BASH
/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! ::

BASH
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. ::

BASH
# 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'
BASH
# 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
BASH
# 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

BASH
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.

BASH
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

BASH
npm i -g @openai/codex

::tip

target: _blank to: https://chatgpt.com/codex

Learn how to install OpenAI's CLI, codex! ::

Claude Code CLI

BASH
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.

BASH
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. ::

BASH
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.

TEXT
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:

BASH
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.

http://librecad.org/

https://github.com/LibreCAD/LibreCAD/releases/

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.

BASH
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

BASH
sudo rm -rf /Library/Frameworks/Python.framework/Versions/3.14

Step 2: Remove the Python Application

  1. Open Finder and go to Applications.
  2. Move any Python 3.14 application to the Trash.
  3. Right-click Trash and choose Empty Trash.

Step 3: Remove Symbolic Links

BASH
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

BASH
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

TEXT
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:

BASH
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

BASH
sudo pmset -a sleep 0 displaysleep 0 disksleep 0
  • sleep 0 — never sleep the system
  • displaysleep 0 — never sleep the display
  • disksleep 0 — never sleep the disk

Auto-Restart After Power Failure

BASH
sudo pmset -a autorestart 1

Verify Settings

BASH
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

External References

RFD 0003 · macOS Workflows and Setup