Skip to content

Instantly share code, notes, and snippets.

@bguiz

bguiz/mac-setup.md

Last active November 20, 2025 14:05
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save bguiz/7658b3dd274ae84a1c45eeba4bc9f013 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save bguiz/7658b3dd274ae84a1c45eeba4bc9f013 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
mac-setup.md

Status: WIP

Install software via brew

mkdir -p ~/code/
cd ~/code/

# Install brew itself
curl -fsSL "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh" > brew-install.sh
/bin/bash ./brew-install.sh

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ${HOME}/.zprofile

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

brew doctor

# Install software from brew direct

brew install \
	uv \
	ack \
	aescrypt \
	ascii \
	asciidoctor \
	asciinema \
	gnupg \
	pinentry-mac \
	nvm \
	jq \
	visual-studio-code \
	git \
	bash \
	bcrypt \
	cairo \
	gradle \
	go \
	solc-select \
	ffmpeg \
	imagemagick \
	woff2 \
	yt-dlp \
	tree \
	orbstack \
	go \

# Install software from brew taps

brew tap oven-sh/bun

brew install \
	bun \

# Install software from brew casks
		
brew install --cask \
	http-toolkit \
	vlc \
	android-studio \
	google-chrome \
	cleanmymac \
	cmake \
	firefox@developer-edition \
	brave-browser \
	obsidian \
	android-ndk \
	android-commandlinetools \
	android-file-transfer \
	androidtool \
	asciidocfx \
	temurin \
	http-toolkit \
	vlc \
	nordvpn \
	firefox \
	zoom \
	loom \
	temurin \

# Periodically update installed software to latest versions

brew upgrade

brew doctor

Git + SSH set up

Edit all at once using git config --global --edit.

  • Easier to interpret markings in merge conflicts + diffs
  • Specify default branch as main instead of master
  • If you have a typo in your git subcommands, instead of saying “did you mean …?” and then exiting, automatically do what it thinks your meant, with a 30s delay for you to Ctrl+C in case it guessed wrong
  • Always use ISO-8601 timestamps instead of the default (RFC-2822 format, IIRC)
merge.conflictstyle=zdiff3
diff.algorithm=histogram
push.default=current
init.defaultbranch=main
help.autocorrect=30
branch.sort=-committerdate
tag.sort=-taggerdate
log.date=iso-strict

See [git config, optional extras]?? section below for more details.

less setup

Add to you preferred shell startup script (e.g. .bashrc, .zshrc, .profile, .zprofile, etc)

  • Do not reset the screen
  • Allow the control characters, only for ANSI colour sequences
  • Quit immediately if the output is small enough to fit on screen
  • Suppress terminal bell
  • Temporarily highlight the first new line after jumping forward (indicate where you were before the jump)
  • Suppress line numbers
export LESS='-XRFQWn'

GPG

which pinentry-mac
# /opt/homebrew/bin/pinentry-mac

touch ~/.gnupg/gpg-agent.conf
vim ~/.gnupg/gpg-agent.conf
# edit the file to explicitly specify location of pinentry-mac,
# otherwise you're likely to run into "ioctl" errors, such as:
# gpg: signing failed: Inappropriate ioctl for device
: <<'>>>'
pinentry-program /opt/homebrew/bin/pinentry-mac
>>>

killall gpg-agent
# force gpg to restart, necessary after installation of pinentry-mac

gpg --version
# gpg (GnuPG) 2.4.0
# ...

gpg --full-generate-key
# Kind of key: (1) RSA and RSA
# Key size: 4096
# Valid for: 0 (does not expire)
# Real name: Brendan Graetz
# Email: [email protected]
# Comment: For github.com/bguiz
# Okay
# Enter new passphrase twice

gpg --list-secret-keys --keyid-format=long
# should see the one you just created
# and it should have a "sec" section
# copy the key ID, "27CE20CCA1E332F9" in this example

clear
# don't leave that on the screen
# close your terminal window/ tab and reopen it (better)

echo "test" | gpg --status-fd=2 -bsau 27CE20CCA1E332F9
# GPG sign a test message with your new key as a sanity check.
# This is the same command that git uses to GPG sign your commits.
# This can fail for a number of different reasons,
# such as incorrecty pin, or pinentry not connected to GPG properly.
# If it works, you should see "SIG_CREATED" followed by "-----BEGIN PGP SIGNATURE-----".
# If it does not work, debug: https://stackoverflow.com/a/55993078/194982

gpg --armor --export 27CE20CCA1E332F9 | pbcopy
# the ID is copied from the list command earlier
# this copies the exported version to clipboard

# Browser: https://github.com/settings/keys --> https://github.com/settings/gpg/new
# Paste into "key" text area, check that it
#   begins with "-----BEGIN PGP PUBLIC KEY BLOCK-----" and
#   ends with "-----END PGP PUBLIC KEY BLOCK-----"
# give it a title of your choice
# Press "add gpg key"

SSH + Git + Github

git --version
# git version 2.37.1 (Apple Git-137.1)

git config --global user.email "[email protected]"
git config --global user.name "Brendan Graetz"
# set email and name to use (by default) in git commits,
# as well as in "Signed-off-by:" (when using `git commit -s`).

git config --global user.signingkey 27CE20CCA1E332F9
# set as the default signing key
# note that gpg alone is insufficient to use github, for that we need ssh

git config --global commit.gpgsign true
# tell git to GPG sign all your commit messages
mkdir -p ~/.ssh

ssh -V
# OpenSSH_9.0p1, LibreSSL 3.3.6

ssh-keygen -t ed25519 -C "[email protected]"
# filename: /Users/user/.ssh/github_id_ed25519
# passphrase: (empty)

ls -al ~/.ssh
# should see  "github_id_ed25519" and "github_id_ed25519.pub"

touch ~/.ssh/config
# create file if it does not exist

vim ~/.ssh/config
# edit the file to include the following
: <<'>>>'
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile /Users/user/.ssh/github_id_ed25519

>>>

ssh-add --apple-use-keychain /Users/user/.ssh/github_id_ed25519
# Identity added: /Users/user/.ssh/github_id_ed25519 ([email protected])

pbcopy < /Users/user/.ssh/github_id_ed25519.pub
# copy the public key to clipboard

# Browser: https://github.com/settings/keys --> https://github.com/settings/ssh/new
# paste the key into text area
# key type is "authentication"
# add any title of your choice
# press " add ssh key"

ssh -T [email protected]
# Hi bguiz! You've successfully authenticated, but GitHub does not provide shell access.
# If you get this output, SSH is set up correctly
# Try to git clone a repo, or push a commit, as well as an additional check

When performing git commit,

  • -S is for GPG signatures, if you have commit.gpgsign set in the global git config, as done above, you can leave it out when using the git CLI command
  • -s is for the sign off commit message suffix, but git does not support a git config for this, unfortunately, and you are need to remember to include it every time you use the git CLI command
    • If your project uses husky (or equivalent local pre-commit checks), consider adding [something similar to this]??? so that it fails fast and fails locally should you forget the flag.
    • If you are keen, there’s a workaround for this that makes use of git hooks and git-interpret-trailers: https://stackoverflow.com/a/46536244/194982

git config, optional extras

git config --global merge.conflictstyle zdiff3
# more usable merge conflicts:
# shows the original commit in addition to target branch and to-merge branch

git config --global diff.algorithm histogram
# more usable git diffs:
# especially when sections of code are re-ordered

git config --global push.default current
# prevent accidentally pushing to a remote branch with a different name
# (when unspecified)

git config --global init.defaultBranch main
# useful if your github user default or the github org default specifies `main` as well

git config --global help.autocorrect 30
# e.g. `git commit` gets auto corrected to `git commit` after 1s

git config --global branch.sort -committerdate
git config --global tag.sort -taggerdate
# sorts branches and tags by most recent first (default is alphabetical)

git config --global log.date iso-strict
# date as `YYYY-MM-DD hh:mm:ss` instead of the natural language default

For more options and detailed explanations, see: https://jvns.ca/blog/2024/02/16/popular-git-config-options/

Verify git + gpg

The “DC0” checks on Github inspect your commits in a manner similar to this:

mkdir test-git-repo
cd test-get-repo
git init
echo "# test-git-repo" > README.md
git add README.md
git commit -s -S -m "proj: initial commit"
git verify-commit --raw HEAD
# This verifies that your git commit was indeed GPG signed,
# it should produce output similar to this:
# [GNUPG:] NEWSIG
# [GNUPG:] KEY_CONSIDERED <...............redacted...............> 0
# [GNUPG:] SIG_ID dK8maH6zv0IA0cBA+CsyOYD+J84 2023-07-25 1690267423
# [GNUPG:] KEY_CONSIDERED <...............redacted...............> 0
# [GNUPG:] GOODSIG 27CE20CCA1E332F9 Brendan Graetz (For github.com/bguiz) <[email protected]>
# [GNUPG:] VALIDSIG <...............redacted...............> 2023-07-25 1690267423 0 4 0 1 8 00 <...............redacted...............>
# [GNUPG:] TRUST_ULTIMATE 0 pgp

git log --format=%B -n 1    
# This verifies that your git commit was indeed signed off (`-s`),
# it should produce output containing a "Signed-off-by":     
# docs: add hscs workshop - index page + setup only
#
# Signed-off-by: Brendan Graetz <[email protected]>

NodeJs

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# close and re-open shell to load new env vars

nvm install --lts
# install the latest LTS version of nodejs

node -v
# v18.15.0

npm -v
# 9.5.0

nvm alias default 18
# default -> 18 (-> v18.15.0)

brew install pnpm
# additional package manager (optional)

Java

which java
# where java is accessed from your shell. note that this may be a symlink.

java -version
# ensure that JRE is installed, acessible, and the right version (v21 or higher)

javac -version
# ensure that JDK is installed, accessible,
# and the right version (v21 or higher)

gradle -v
# ensure that gradle is installed, accessible,
# and the right version (v21 or higher)

brew update
brew upgrade --cask temurin
brew upgrade gradle
# if you already have java/ gradle installed, but it is an older version

Golang

go version
# ensure that golang is installed, accesible,
# and the right version (v1.22 or higher)

brew update
brew upgrade go
# if you already have go installed, but it is an older version

Solidity

## Option 1 - recommended

uv tool install solc-select
uv tool update-shell
# install solc via uv

solc-select install 0.8.24
solc-select use 0.8.24
solc --version
# install and switch to a specific version of solc

## Option 2 - not recommended

brew tap ethereum/ethereum
brew install solidity
# install solc via brew, latest version only

Useful Apps

jq
# CLI tool useful in parsing JSON, e.g. JSON-RPC responses

visual-studio-code
# VS Code

brave-browser
# install Brave (chromium-based browser)

firefox@developer-edition
# install Firefox Dev Edition (non-chromium nased browser)
# recommended extenstions
# https://addons.mozilla.org/en-US/firefox/addon/multi-account-containers/
# https://addons.mozilla.org/en-GB/firefox/addon/youtube-audio/
# https://addons.mozilla.org/en-GB/firefox/addon/onetab/
# https://addons.mozilla.org/en-GB/firefox/addon/ublock-origin/

imagemagick
# command line image processing

ffmpeg
# command line video processing

yt-dlp
# download youtube video/ audio (useful in combination with ffmpeg)

woff2
# gives you woff2_decompress, used to convert *.woff2 to *.ttf

http-toolkit
# intercept and modify HTTP requests

vlc
# media player, good alternative to quicktime

VS Code set up

  • enable github copilot
    • requires github org to include your username under their plan → ask engineering
  • enable MCP support in VS code
    • vscode://settings/chat.mcp.enabled
      • note that this requires githurb org to allow it centrally
  • install plugin Cline, for genAI/ vibe coding:

    • vscode:extension/saoudrizwan.claude-dev

    • press “Install” button

    • press Cline button in vertical side bar (robot face with squiggly brackets icon)

      • complete wizard
      • press “use your own API key”
      • API Provider: select OpenRouter
      • OpenRouter API key: copy-paste from openrouter dashboard
      • press “Let’s go” button

    • go to settings (gear icon at top) → API configuration

      • press “plan mode” tab
      • model: selectanthropic/claude-3.7-sonnet
      • enable extended thinking: select true
      • budget: select ~5000 tokens
      • use different models for plan and act modes: select true
      • press “act mode” tab
      • model: select anthropic/claude-sonnet-4
      • enable extended thinking: select true
      • budget: select ~5000 tokens
      • press “save” button

    • go to settings (gear icon at top) → general settings

      • allow anonymous error and usage reporting: select false
      • press “save” button

    • go to settings (gear icon at top) → feature settings

      • enable checkpoints: select true
      • enable MCP marketplace: select true
      • collapse MCP responses: select true
      • press “save” button

    • go to MCP servers (3 stacked rectangles icon at top)

      • press “installed” tab
      • press “configure MCP servers” button
      • a code tab for $PLUGIN_DIR/settings/cline_mcp_settings.json opens
      • edit this file to include your MCP server configuration
      • example settings for $PLUGIN_DIR/settings/cline_mcp_settings.json file
      {
  "mcpServers": {
    "nameOfMcpServer": {
      "command": "npx",
      "args": [
        "-y",
        "some-mcp-server@latest"
      ],
      "type": "stdio"
    }
  }
}
      • press “done” button

    • upon first prompt

      • press the “>” button on the “auto-approve” line
      • MCP: select true
      • then continue with the prompt
  • install plugin: Roo Codes, for genAI/ vibe coding
    • vscode:extension/RooVeterinaryInc.roo-cline
    • press “install” button
    • press Roo Codes button in vertical side bar (kangaroo icon)
      • in wizard, scroll to section: Bring Your Own API Key
      • press “use your own API key”
      • API Provider: select OpenRouter
      • OpenRouter API key: copy-paste from openrouter dashboard
      • Model: anthropic/claude-sonnet-4
      • OpenRouter Provider Routing: [default]
      • Enable reasoning: select true
      • Max tokens: 16384
      • Max thinking tokens: 8192
      • press “Let’s go” button
      • Help Improve Roo Code: press “deny” button
    • go to MCP servers (3 stacked rectangles icon at top)
      • enable MCP servers: select true
      • enable MCP server creation: select false
      • press “edit project MCP” button
      • the file $PROJECT_DIR/roo/mcp.json should open in your code editor tab
      • edit this file to include MCP servers (same format as for Cline)
      • press “refresh MCP servers” button
      • you should see the MCP servers that you have configured appear above the buttons
      • press the “done” button
    • upon first prompt
      • press the “>” button on the “auto-approve” line
      • MCP: select true
      • underneath the prompt text box, select the intended “roo mode”
      • then continue with the prompt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment