Skip to content

SETUP.md

Latest commit

 

History

History
521 lines (358 loc) · 13 KB

SETUP.md

File metadata and controls

521 lines (358 loc) · 13 KB
Raw

New mac setup guide

Setup guide for a new machine based on these dotfiles.

Bootstrap (before anything else)

Xcode command line tools

xcode-select --install

This provides git and other essential build tools.

Show hidden files in Finder

defaults write com.apple.finder AppleShowAllFiles YES && killall Finder

Package manager and core tools

Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

For this session only (until Fish is set up):

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

Once Fish is installed and stowed, your config.fish handles the PATH automatically.

Fish shell

brew install fish
# Add to allowed shells
echo /opt/homebrew/bin/fish | sudo tee -a /etc/shells
# Set as default
chsh -s /opt/homebrew/bin/fish

Fisher (fish plugin manager)

curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher

Fish plugins to install:

fisher install jethrokuan/z          # Directory jumping (the 'j' alias)
fisher install PatrickF1/fzf.fish    # FZF integration

Cli power tools

# Essential CLI tools
brew install bat          # Better cat
brew install eza          # Better ls
brew install fzf          # Fuzzy finder
brew install ripgrep      # Better grep (rg)
brew install fd           # Better find
brew install trash        # Safe rm alternative
brew install yazi         # Terminal file manager
brew install zellij       # Terminal multiplexer
brew install delta        # Even prettier diffs
brew install jq

Tools

brew install git # note: check if xcode-select already installed git
brew install git-lfs
git lfs install
brew install gh
brew install diff-so-fancy # Pretty git diffs
brew install lazygit      # Git TUI
brew install starship
brew install neovim
brew install pngpaste
brew install stow
brew install tree-sitter tree-sitter-cli
brew install ghostty
rm -rf ~/Library/Application\ Support/com.mitchellh.ghostty # to remove default config file
brew install shellcheck   # Shell script linter
brew install helm
brew install terraform
brew install zig         # Cross-compiler
brew install direnv      # Auto-load .envrc files (used by tu for Terraform)
brew install --cask session-manager-plugin # for aws ssm connection

Kubernetes tools

brew install kubectl
brew install k9s
brew install lens

Karabiner

Download from: https://karabiner-elements.pqrs.org/

After stowing or making changes to the config, restart Karabiner:

killall karabiner_console_user_server && open -a "Karabiner-Elements"

cmux

Download from: https://github.com/manaflow-ai/cmux

After stowing, cmux picks up ~/.config/cmux/cmux.json on next launch.

treehouse

Pooled, reusable git worktrees so each agent session gets an isolated tree without re-cloning: https://github.com/kunchenguid/treehouse

curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh

After stowing, treehouse reads ~/.config/treehouse/config.toml as the user-level config. A repo-level treehouse.toml (created by treehouse init) overrides it per repository, except for hooks, which are user-level only for safety.

The th alias in config.fish drops you into a pooled worktree; exit returns it to the pool.

Github config

Ssh keys

Generate a new SSH key using Ed25519 (modern, fast, secure):

ssh-keygen -t ed25519 -C "email address"

What is Ed25519? It's an elliptic curve algorithm that produces smaller keys (256 bits) with the same security as RSA 4096-bit keys, but faster. It's what GitHub recommends.

Start the SSH agent and add your key:

eval (ssh-agent -c)

Create or edit ~/.ssh/config (replace id_ed25519 with your key filename if different):

mkdir -p ~/.ssh
printf '%s\n' \
  'Host github.com' \
  '  AddKeysToAgent yes' \
  '  UseKeychain yes' \
  '  IdentityFile ~/.ssh/id_ed25519' \
  >> ~/.ssh/config

Add the key to your Mac OS keychain (replace id_ed25519 if you used a different name):

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Copy the public key to clipboard:

pbcopy < ~/.ssh/id_ed25519.pub

Add it to GitHub:

  1. Go to https://github.com/settings/keys
  2. Click "New SSH key"
  3. Paste the key and save

Test the connection:

ssh -T git@github.com

You should see: "Hi carlisia! You've successfully authenticated..."

Github cli

gh auth login

Agent tooling (AXI)

Agent-ergonomic CLIs built on the AXI principles. Both install as global Agent Skills rather than npm packages: the skill is a small discovery stub and the CLI is fetched fresh via npx, so there is nothing to keep updated. Skills land in ~/.agents/skills/ and are symlinked into ~/.claude/skills/. Restart the agent session after installing one.

gh-axi

Agent-ergonomic wrapper around gh that emits TOON instead of JSON, so agents spend fewer tokens on GitHub work: https://github.com/kunchenguid/gh-axi

npx -y skills add kunchenguid/gh-axi --skill gh-axi -g

This writes ~/.agents/skills/gh-axi/ and symlinks it into ~/.claude/skills/. Requires Node 20+ and an authenticated gh (see above). Verify with npx -y gh-axi inside any repo.

Two optional capabilities have extra prerequisites:

  • Stacked PR commands (gh-axi stack ...) need gh extension install github/gh-stack.
  • --attach on issue/PR create, edit, and comment needs gh >= 2.99.0. Older gh returns a structured error before any mutation runs, so it fails safely.

lavish-axi

Opens agent-generated HTML artifacts in a local browser so you can annotate elements and text, edit Mermaid diagrams as whiteboards, and send the feedback straight back to the agent: https://github.com/kunchenguid/lavish-axi

npx -y skills add kunchenguid/lavish-axi --skill lavish -g

Unlike gh-axi this one is user-invocable, so /lavish <what to show> works as a slash command in Claude Code. It also loads on its own when a response would land better as a page than as prose.

Runtime notes worth knowing:

  • It runs a local server on port 4387 (LAVISH_AXI_PORT to change). npx -y lavish-axi stop shuts it down; it also self-stops after 30 idle minutes.
  • Session state lives in ~/.lavish-axi/ (LAVISH_AXI_STATE_DIR to relocate). Artifacts default to .lavish/ in the working directory.
  • Binding is loopback-only unless Tailscale is running, in which case it also binds this machine's tailnet address so you can review from a phone. That server is unauthenticated and can serve local files, so only enable it on a tailnet you trust. Tailscale is not installed here, so it is loopback-only today.
  • lavish-axi share publishes to ht-ml.app, a third-party host, and is public by default. It has no delete endpoint and a password cannot be removed once set, so treat every share as permanent and use --private deliberately.

Dotfiles

Clone the dotfiles

mkdir -p ~/code/src/github.com/carlisia
cd ~/code/src/github.com/carlisia
git clone git@github.com:carlisia/dotfiles.git

My tools

Install markin

Stow dotfiles

After cloning the dotfiles, create symlinks for all configurations.

This can be done before installing the actual tools - the configs will be ready when you install each tool.

cd ~/code/src/github.com/carlisia/dotfiles

# Shell and terminal
stow fish -t $HOME
stow starship -t $HOME
stow ghostty -t $HOME

# Development tools
stow gh -t $HOME
stow git -t $HOME
stow nvim -t $HOME
stow markdownlint -t $HOME
stow shellcheck -t $HOME

# CLI utilities
stow bat -t $HOME
stow eza -t $HOME
stow yazi -t $HOME
stow zellij -t $HOME
stow lazygit -t $HOME
stow treehouse -t $HOME

# Kubernetes tools
stow k9s -t $HOME

# Mac apps
stow karabiner -t $HOME
stow cmux -t $HOME

stow markin -t $HOME

Fonts

brew install --cask font-fira-code
brew install --cask font-jetbrains-mono
brew install --cask font-symbols-only-nerd-font
brew install --cask font-maple-mono

Ghostty config uses: Fira Code, Maple Mono, Symbols Nerd Font

Essential apps

OS accessibility permissions

For global keybindings to work (like ctrl+shift+p for the quick terminal), Ghostty needs Accessibility permissions. Ensure this is set:

  1. Open System Settings → Privacy & Security → Accessibility
  2. Look for Ghostty in the list and enable it
  3. If Ghostty isn't listed, click the + button and add it from /Applications/
  4. Restart Ghostty after granting permissions

Shared apps

Alfred

Download from: https://www.alfredapp.com/

  1. Install and enter Powerpack license
  2. Set up syncing: Go to Advanced tab → Syncing section → "Set preferences folder..."
  3. Enable automatic snippet expansion: Features → Snippets → Automatically expand snippets by keyword (if not already set)
  4. Check clipboard settings: Features → Clipboard History → Configure history limits and preferences

Moom

Download from: https://manytricks.com/moom/

  1. Install and enter license
  2. Import custom actions: Preferences → Custom → Import → Select Actions.moom file

Dash

Download from: https://kapeli.com/dash

Enable Alfred integration: Preferences → Integration → Alfred

Bartender

Download from: https://www.macbartender.com/

  1. Install and enter license
  2. Configure menu bar items as desired

Sharing config between machines:

Bartender stores settings in ~/Library/Preferences/com.surteesstudios.Bartender.plist.

Keyboard Maestro

Steer Mouse

Not shared by config files

  • cleanshot

  • el gato control center

  • apptorium

    • sidenotes
    • fivenotes
    • cursor teleporter

Other apps

Development languages

Go

brew install go

Config expects: GOPATH=~/code and GOBIN=~/code/bin

Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Python

brew install python

Node.js

brew install node

Required for various LSP servers and formatters.

Environment variables

set --Ugx SECOND_BRAIN (using Obsidian remote, this path will be the local vault, not the remote)

Additional dependencies

Install shell-color-scripts for nvim/nvchad/snack dashboard:

curl -L https://gitlab.com/dwt1/shell-color-scripts/-/archive/master/shell-color-scripts-master.tar.gz | tar xz -C /tmp
mkdir -p ~/.local/bin ~/.local/share/shell-color-scripts
cp -rf /tmp/shell-color-scripts-master/colorscripts ~/.local/share/shell-color-scripts/
cp /tmp/shell-color-scripts-master/colorscript.sh ~/.local/bin/colorscript
chmod +x ~/.local/bin/colorscript

Install Lua 5.1 for compatibility:

cd /tmp
curl -L https://www.lua.org/ftp/lua-5.1.5.tar.gz | tar xz
cd lua-5.1.5/src && make macosx
mkdir -p ~/.local/lua51/bin
cp lua luac ~/.local/lua51/bin/
ln -sf ~/.local/lua51/bin/lua ~/.local/bin/lua5.1

Install jsregexp for LuaSnip (needed for LSP snippet transformations):

luarocks --local --lua-version 5.1 install jsregexp

Lsp servers and tools

Install Lua tools:

brew install lua-language-server
brew install stylua
brew install luarocks
luarocks install luacheck

Install Fish tools:

brew install fish-lsp

Install Python tools:

brew install basedpyright

Install Bash tools:

npm install -g bash-language-server
go install mvdan.cc/sh/v3/cmd/shfmt@latest

Install Prettier:

npm install -g @fsouza/prettierd

Install Markdown tools:

brew install markdownlint-cli

Git commits - gpg commit signing

Install GPG tools:

brew install gnupg
brew install pinentry-mac

Generate GPG keys (one for personal, one for work):

# Personal key
gpg --quick-generate-key "Your Name <personal@email.com>" rsa4096 default 0

# Work key
gpg --quick-generate-key "Your Name (Work) <work@email.com>" rsa4096 default 0

List your keys to get the key IDs:

gpg --list-secret-keys --keyid-format=long

Update the signing keys in:

  • ~/.config/git/config - personal key ID
  • ~/.config/git/config-work - work key ID

Configure pinentry for Mac Keychain integration:

echo "pinentry-program /opt/homebrew/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

This enables GPG passphrase caching via Mac OS Keychain. On your first commit with each key, you'll be prompted for the passphrase with an option to save it to Keychain. After that, commits won't require re-entering the passphrase.

Optional

brew install --cask visual-studio-code  # Git difftool
brew install coreutils                  # GNU coreutils