Tip
The whole idea: install Claude Code first (~10 min, you do it). Then copy 8 prompts from this gist, one at a time, into Claude. Claude installs everything else for you. Total time: ~30 min of you doing things + ~60 min of Claude working in the background.
Old way: copy 50 commands into your terminal, one by one, hoping you don't fat-finger a rm -rf.
This way:
- You do Phase 0 yourself (5 commands, all explained).
- Then for each of Phases 1-8 you:
- Read the "What this does" line so you know what's happening.
- Copy the prompt block.
- Paste it into Claude.
- Sit back. Claude will pause if it needs you to click something or sign into something — it tells you exactly what to do.
- When you see ✅ PHASE N DONE in Claude's output, type
/clearin Claude and paste the next phase.
Files in this gist:
piyush-mac-setup.md— this walkthrough (the file you're reading)Brewfile— list of apps + CLI tools to install (Claude downloads this in Phase 4 / 5)claude-skills-install.sh— backup script for Phase 6 if Claude strugglesverify.sh— final health-check script
Claude will sometimes stop and ask you to do something manually. This is normal — there are things Claude can't do on a Mac:
- Click a button in System Settings (Apple security — no AI can click those)
- Scan a QR code with your phone (WhatsApp, Signal)
- Enter a license key or sign into an app
- Approve a browser OAuth flow
When Claude stops, you'll see a banner like this:
🛑 ============== ACTION REQUIRED ==============
What to do: Open System Settings → Privacy → Accessibility
Enable Raycast. Enter your password.
When done: Reply "done"
============================================
Just do what it says, then type done (or skip) in Claude. Claude continues from there.
Expect ~16 of these stops across all 8 phases. Most are 10 seconds each. Total interactive time: ~30 min.
Important
What this does: Installs Apple's developer tools (git, compiler), Homebrew (the Mac package manager), Node.js, and Claude Code itself. Why manual: Claude doesn't exist on your machine yet — you have to install it first. ~15 min total.
- System Settings → Apple Account → sign in with your Apple ID
- This is needed so the App Store works (later, Claude installs apps via
mas, the Mac App Store CLI — that requires you to be signed in first). - Leave iCloud Drive Documents & Desktop sync OFF — syncs your entire home folder to iCloud, slows everything down.
Open Terminal.app (Spotlight → "Terminal") and paste:
xcode-select --installA popup appears. Click Install → accept the license → wait. Downloads about 2 GB. This installs git, the C compiler, and Python headers. Without it, nothing else works.
When done, verify:
git --version
# Should print something like: git version 2.39.xPaste into Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"It'll ask for your Mac login password (the one you use to log into your Mac, NOT your Apple ID). Type it (you won't see the characters as you type — that's normal). Press Enter.
At the end, Homebrew prints 2 lines that look like this — copy and paste them into Terminal:
echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"Verify:
brew --version
which brew
# MUST output: /opt/homebrew/bin/brewWarning
If which brew shows /usr/local/bin/brew, that's wrong (the Intel Mac path). Re-run the installer.
brew install node
npm install -g @anthropic-ai/claude-codeclaudeA browser opens. Sign into your Anthropic account (Pro or Max plan — free tier won't get you Opus model access).
When you come back to the terminal, macOS will show a Keychain dialog:
"claude wants to access key in your keychain"
Click "Always Allow" (NOT just "Allow" — Always Allow means Claude won't pester you on every command). If you click the wrong one, every Claude operation will trigger another popup.
Type /exit to quit Claude for now.
Open Claude again:
claudeYou're ready to paste Phase 1 below.
Important
What this does: Installs Ghostty (a modern terminal that looks gorgeous on macOS Tahoe — frosted glass, smooth ligatures, JetBrains Mono font). Also installs notification hooks so Claude makes a sound when it needs you. ~5 min.
You'll do: Open Ghostty once after install, click "Allow" if macOS asks for notification permission.
Success looks like: A new terminal window with a transparent frosted-glass background, the prompt rendering with crisp ligatures (e.g. == and => look like single elegant characters).
Copy ↓, paste into Claude:
You are helping Piyush, a junior-mid Mac developer at Nitya Capital, set up his brand-new MacBook (macOS 26 Tahoe, May 2026). He just finished Phase 0 (Homebrew + Node + Claude Code installed, Apple ID signed in). Now do Phase 1: install Ghostty terminal, configure it premium-style, and wire notification sounds.
BEFORE YOU START
1. Register every step below as a todo via your task-tracking tool. Mark in_progress before each, completed after.
2. Run a preflight check — `which brew` must return `/opt/homebrew/bin/brew`. If it doesn't, STOP and tell Piyush: "Phase 0 wasn't completed correctly — re-run `eval \"$(/opt/homebrew/bin/brew shellenv)\"` and try again."
STOP RULES
- If macOS will show a sudo password prompt, GUI dialog, or browser OAuth → print a 🛑 ACTION REQUIRED banner and wait for Piyush to type "done" (or "skip").
- Banner format:
🛑 =========== ACTION REQUIRED ===========
What: <one sentence>
Where: <exact menu path or app name>
Then: reply "done"
=======================================
- Do NOT try to bypass these — Piyush is sitting at the keyboard, this is fine.
STEPS
1. Install Ghostty and the JetBrains Mono Nerd Font:
```
brew install --cask ghostty font-jetbrains-mono-nerd-font
```
This may take 1-2 min and ask for Piyush's Mac password (Gatekeeper). Print the STOP banner if so.
2. Write the premium Ghostty config to `~/.config/ghostty/config`:
```bash
mkdir -p ~/.config/ghostty && cat > ~/.config/ghostty/config <<'EOF'
# ~/.config/ghostty/config — premium glass setup for macOS 26 Tahoe
theme = Catppuccin Macchiato
font-family = JetBrainsMono Nerd Font
font-size = 14
font-feature = +liga
font-feature = +calt
font-feature = +ss01
font-feature = +ss02
font-thicken = true
background-opacity = 0.92
background-blur = macos-glass-regular
window-colorspace = display-p3
macos-titlebar-style = transparent
macos-titlebar-proxy-icon = visible
macos-window-shadow = true
macos-option-as-alt = left
macos-icon = official
window-padding-x = 14
window-padding-y = 12
window-padding-balance = true
window-save-state = always
cursor-style = bar
cursor-style-blink = true
mouse-hide-while-typing = true
confirm-close-surface = false
quit-after-last-window-closed = true
copy-on-select = clipboard
shell-integration = detect
shell-integration-features = cursor,sudo,title
EOF
```
3. Set up Claude Code notification hooks so Piyush hears a sound when a phase finishes or Claude needs his input. Write/merge into `~/.claude/settings.json`:
```json
{
"hooks": {
"Notification": [{
"hooks": [{
"type": "command",
"command": "osascript -e 'display notification \"Claude needs you\" with title \"Claude Code\" sound name \"Glass\"'"
}]
}],
"Stop": [{
"hooks": [{
"type": "command",
"command": "afplay /System/Library/Sounds/Hero.aiff"
}]
}]
}
}
```
If `~/.claude/settings.json` already has content, MERGE (don't clobber) — read the existing JSON first, add the `hooks` key, write back.
4. STOP banner — tell Piyush:
🛑 OPEN GHOSTTY NOW
What: Cmd+Space → type "Ghostty" → Enter. If macOS shows "Ghostty is from the internet" → click Open.
If it asks about Notifications → click Allow.
Then: Reply "done" — I'll continue.
5. After Piyush replies "done", verify by checking:
- `[[ -f ~/.config/ghostty/config ]]` → true
- `[[ -f ~/.claude/settings.json ]]` → true
- Ghostty process running: `pgrep -x Ghostty`
6. Print:
========================================
✅ PHASE 1 DONE — Ghostty + premium config + notification hooks
Proof:
- Ghostty installed, config at ~/.config/ghostty/config
- JetBrains Mono Nerd Font in ~/Library/Fonts/
- Notification hooks in ~/.claude/settings.json
Next: type /clear in Claude, then paste Phase 2 from the gist.
Optional: switch to Ghostty (Cmd+Tab) and run `claude` there — better experience.
========================================
Important
What this does: Makes your terminal much smarter. Auto-suggests commands you've typed before (press → to accept). Colors valid commands green and typos red BEFORE you press Enter. Adds a beautiful prompt with your current folder, git branch, and language version. ~3 min.
You'll do: Nothing — fully automatic. (You might be asked your name/email for git in Phase 3, not here.)
Success looks like: Your prompt shows ~/projects ❯ with an icon, and faded ghost text appears as you type recalled commands.
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. He finished Phase 1 (Ghostty installed). Now do Phase 2: install oh-my-zsh, Starship, and zsh plugins for a smart, modern shell.
BEFORE YOU START
1. Register every step below as a todo via your task-tracking tool.
2. Preflight: `which brew` returns /opt/homebrew/bin/brew. If not, STOP and tell Piyush Phase 0 broke.
CRITICAL GOTCHA — oh-my-zsh installer
The vanilla installer:
(a) prompts to change shell (asks for password — would hang you), AND
(b) launches a new zsh subshell (would halt your bash session), AND
(c) backs up any existing ~/.zshrc and writes its own.
Use these env vars to fix ALL THREE: `RUNZSH=no CHSH=no KEEP_ZSHRC=no`
- KEEP_ZSHRC=no LETS oh-my-zsh write its template ON A FRESH MAC (Piyush has no existing .zshrc). This is what we want — Phase 3 will append to OMZ's template, not the other way around.
STEPS
1. Install oh-my-zsh, NON-INTERACTIVELY (this is the only way it works in a Claude subprocess):
```bash
RUNZSH=no CHSH=no sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
```
2. Install Starship (the prompt) via brew:
```bash
brew install starship
```
3. Clone the two zsh plugins into oh-my-zsh's custom directory:
```bash
git clone https://github.com/zsh-users/zsh-autosuggestions \
${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting \
${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
```
4. Edit `~/.zshrc` to:
(a) enable the plugins (change the `plugins=(git)` line to `plugins=(git zsh-autosuggestions zsh-syntax-highlighting)`)
(b) APPEND a starship init line at the end of the file
```
eval "$(starship init zsh)"
```
5. Write a Starship config to `~/.config/starship.toml` — keep it simple and premium (NO neon, NO emoji-spam, just clean info):
```toml
"$schema" = "https://starship.rs/config-schema.json"
format = """
$directory\
$git_branch\
$git_status\
$nodejs\
$python\
$cmd_duration\
$line_break$character"""
[character]
success_symbol = "[❯](bold cyan)"
error_symbol = "[❯](bold red)"
[directory]
style = "bold cyan"
truncation_length = 3
truncate_to_repo = true
[git_branch]
symbol = " "
style = "bold magenta"
[git_status]
style = "bold magenta"
[cmd_duration]
min_time = 500
format = "[took $duration]($style) "
style = "yellow"
```
6. Verify the shell config sources cleanly:
```bash
zsh -i -c 'echo SHELL_OK; type starship'
```
Expected output contains `SHELL_OK` and `starship is /opt/homebrew/bin/starship`.
7. Print:
========================================
✅ PHASE 2 DONE — oh-my-zsh + Starship + autosuggest + syntax highlighting
Proof:
- `~/.oh-my-zsh/` exists
- `which starship` → /opt/homebrew/bin/starship
- `~/.config/starship.toml` written
- plugins line in ~/.zshrc includes zsh-autosuggestions + zsh-syntax-highlighting
Next: open a NEW Ghostty tab (Cmd+T) to see the new prompt. Then /clear and paste Phase 3.
========================================
Important
What this does: Installs version managers for Node and Python (mise, uv) so you can have different versions per project. Configures git with your name/email. Generates an SSH key and uploads it to GitHub so you can git push without typing passwords. ~5 min.
You'll do: (1) Tell Claude your name + GitHub email when it asks. (2) Open a browser and approve GitHub when prompted (2x — once for login, once for the SSH-key-upload permission).
Success looks like: ssh -T git@github.com says "Hi piyush! You've successfully authenticated."
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phase 2 done (smart shell installed). Now do Phase 3: install Node/Python version managers, configure git, generate SSH key, and authenticate to GitHub.
BEFORE YOU START
1. Register every step below as todos.
2. Preflight: `which brew`, `which zsh`, `[[ -d ~/.oh-my-zsh ]]`. If any fails, STOP.
STOP RULES (this phase has TWO mandatory stops)
- When `gh auth login` runs it will print an 8-character code and open a browser. Stop and tell Piyush:
🛑 GITHUB LOGIN
What: Copy the 8-char code from terminal (looks like ABCD-1234).
Browser opens to github.com/login/device — paste the code, click Authorize.
Then: Reply "done"
- After login, you need a 2nd browser flow to add the `admin:public_key` scope (needed to upload SSH keys).
- If you need git identity info (name + email), use AskUserQuestion with sensible defaults.
STEPS
1. Install mise (polyglot version manager), uv (Python tooling), and a fresh git:
```bash
brew install mise uv git
```
2. Wire mise into the shell — add to BOTH files:
- `~/.zprofile` (login shells, non-interactive): `eval "$(mise activate zsh --shims)"`
- `~/.zshrc` (interactive shells): `eval "$(mise activate zsh)"`
Use `cat >> file` with a heredoc. Do NOT duplicate if the line already exists.
3. Install the dev runtimes globally:
```bash
mise use --global node@lts python@3.13
```
This may take 2-3 min (Python builds from source on M-series). Use run_in_background and Monitor.
4. Ask Piyush for git identity via AskUserQuestion. Two questions, one screen if possible:
- "What name should appear on git commits?" (offer "Piyush <LastName>" as the suggestion shape)
- "What email is tied to your GitHub account?" (gmail / company email)
Then:
```bash
git config --global user.name "<answer 1>"
git config --global user.email "<answer 2>"
git config --global init.defaultBranch main
git config --global pull.rebase false
```
5. Generate an SSH key (only if it doesn't already exist — `test -f ~/.ssh/id_ed25519`):
```bash
ssh-keygen -t ed25519 -C "<piyush's email>" -N "" -f ~/.ssh/id_ed25519
```
6. STOP for GitHub login:
🛑 banner as above. Run:
```bash
gh auth login --hostname github.com --git-protocol ssh --web
```
When the 8-char code prints, include it IN the banner so Piyush can copy it. Wait for "done".
7. Add the SSH-key-upload scope (another browser flow):
🛑 banner again. Run:
```bash
gh auth refresh -h github.com -s admin:public_key
```
Wait for "done".
8. Upload the SSH key to GitHub:
```bash
gh ssh-key add ~/.ssh/id_ed25519.pub --title "$(scutil --get ComputerName)"
```
9. Verify GitHub SSH auth (use accept-new to skip the host-key prompt):
```bash
ssh -o StrictHostKeyChecking=accept-new -T git@github.com
```
Expected: "Hi <piyush-github-username>! You've successfully authenticated..."
10. Print:
========================================
✅ PHASE 3 DONE — Node + Python + git config + GitHub SSH auth
Proof:
- `mise current` shows node + python
- `git config user.email` returns Piyush's email
- `ssh -T git@github.com` says "Hi <username>!"
- ~/.ssh/id_ed25519 exists, uploaded to GitHub
Next: /clear, paste Phase 4.
========================================
Important
What this does: Installs ~30 better command-line tools — eza (prettier ls), bat (prettier cat), ripgrep (10× faster grep), lazygit (visual git), jq (JSON), and many more. Each one replaces a clunky default and saves you time daily. ~10 min download.
You'll do: Nothing — automatic. (Long install, you can walk away.)
Success looks like: eza -la shows your home folder with colors + icons + git status per file.
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phase 3 done (runtimes + GitHub auth). Now do Phase 4: install ~30 modern CLI tools via a Brewfile.
BEFORE YOU START
1. Register todos.
2. Preflight: `which brew`, `gh auth status` (should be authed). STOP if either fails.
THIS PHASE HAS NO STOPS — it's a long-running brew bundle. Run it in the background and Monitor.
STEPS
1. Download Piyush's Brewfile from this gist into the current directory:
```bash
curl -sSL https://gist.githubusercontent.com/Aboudjem/da6b37f5d58a9e8b1b238e11a860d3d3/raw/Brewfile -o /tmp/Brewfile-piyush
```
If curl fails, the Brewfile is also visible in the gist UI — Piyush can save it manually. STOP and ask.
2. Split the Brewfile into two passes (formulae now, casks in Phase 5 — casks need sudo, separate handling):
```bash
grep -E '^(brew|tap) ' /tmp/Brewfile-piyush > /tmp/Brewfile-cli
```
3. Pre-cache sudo so brew doesn't hang on any sudo-needing formula (rare but defensive):
🛑 banner:
What: Run `sudo -v` in your terminal NOW (not in Claude). Type your Mac password.
This pre-caches your password for the next 5 min so the brew install runs silently.
Then: Reply "done"
4. Install formulae in the background:
```bash
brew bundle install --file=/tmp/Brewfile-cli --verbose 2>&1 | tee /tmp/brew-cli.log
```
Use run_in_background. Monitor the log for completion ("Homebrew Bundle complete").
5. Activate fzf keybindings (Ctrl+R history search, Ctrl+T find file, Alt+C jump to dir):
```bash
$(brew --prefix)/opt/fzf/install --all --no-bash
```
`--all` says yes to all 3 prompts (autocompletion, keybindings, shell config). `--no-bash` skips bash.
6. Append the runtime hooks for zoxide and fzf to `~/.zshrc` (only if not already there — grep first):
```bash
eval "$(zoxide init zsh)"
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
```
Also append modern-CLI aliases (use eza for ls, bat for cat, etc):
```bash
alias ls='eza --icons --git'
alias ll='eza -la --icons --git'
alias lt='eza --tree --level=2 --icons'
alias cat='bat --paging=never'
alias grep='rg'
alias find='fd'
alias top='btop'
alias g='git'
alias lg='lazygit'
```
7. Source ~/.zshrc and verify each tool exists:
```bash
zsh -i -c 'for c in eza bat fd rg fzf zoxide lazygit gh jq mise uv ollama; do command -v $c >/dev/null && echo "✓ $c" || echo "✗ $c MISSING"; done'
```
Every tool should show ✓.
8. Print:
========================================
✅ PHASE 4 DONE — modern CLI stack installed
Proof:
- `brew list --formula | wc -l` >= 33
- `eza --version` works
- `zsh -i -c 'type rg'` returns the ripgrep path
Next: /clear, paste Phase 5. (Phase 5 is the BIG one — many GUI apps + manual sign-ins.)
========================================
Important
What this does: Installs ~28 GUI apps: Cursor (your code editor), Brave/Chrome/Firefox (browsers), Raycast (launcher — replaces Spotlight), Rectangle (window snapping), 1Password, Notion, Slack, etc. ~25 min download + a LOT of permission popups. You'll do: Type your Mac password a few times when popups appear. Then after install, open each app once and grant Accessibility / Screen Recording perms (Claude prints an exact checklist). Phone-paired apps (WhatsApp, Signal, Telegram) need a QR scan from your phone — defer those to the end. Success looks like: All apps appear in Launchpad. Raycast, Rectangle, 1Password ready to sign in.
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phase 4 done (CLI tools installed). Now do Phase 5: install ~28 GUI apps via Brewfile casks, then walk Piyush through the necessary permission grants.
BEFORE YOU START
1. Register todos.
2. Preflight: `which brew`. STOP if missing.
THIS IS THE HARDEST PHASE. Expect ~8 STOP banners:
- sudo password warmup
- Cursor "Install 'cursor' command in PATH" GUI click
- Raycast Accessibility + onboarding wizard
- Rectangle Accessibility
- AltTab Accessibility + Screen Recording
- CleanShot Screen Recording (+ license key)
- 1Password sign-in + Settings → Developer → Integrate CLI + Touch ID
- OrbStack first-launch admin prompt
- (Phone-app QR scans — defer to a final checklist, don't block here)
KNOWN BREAKAGE
- `jordanbaird-ice` cask is BROKEN on macOS Tahoe stable (Ice Bar invisible). Install it, mention it, tell Piyush to either skip or grab beta 0.11.13+ from GitHub releases manually.
- `notion-calendar` requires a Google account — call this out, don't try to auth without one.
STEPS
1. Extract cask lines from the Brewfile:
```bash
grep -E '^cask ' /tmp/Brewfile-piyush > /tmp/Brewfile-casks
```
2. Pre-cache sudo (some casks invoke sudo for /Applications writes):
🛑 banner — "Run `sudo -v` in your terminal now, password please, reply done"
3. Install casks in the background (15-25 min):
```bash
NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 \
brew bundle install --file=/tmp/Brewfile-casks --verbose 2>&1 | tee /tmp/brew-casks.log
```
Use run_in_background + Monitor. If macOS pops a sudo dialog mid-stream, STOP and tell Piyush.
4. After install completes, print this consolidated checklist as a STOP banner — Piyush will work through it:
🛑 ===== OPEN EACH APP ONCE + GRANT PERMS =====
Do these IN ORDER. Reply "done" when finished (about 15 min of clicking).
A. Open Cursor → Cmd+Shift+P → type "Shell Command" → pick "Install 'cursor' command in PATH" → enter password.
B. Open Raycast (Launchpad → Raycast) → walk through onboarding → grant Accessibility when asked
→ in Raycast Settings → General → set Hotkey to Cmd+Space
→ System Settings → Keyboard → Keyboard Shortcuts → Spotlight → uncheck Cmd+Space (so they don't fight)
C. Open Rectangle (Launchpad) → click "Open System Settings" on the prompt → enable Rectangle under Privacy → Accessibility.
D. Open AltTab → grant Accessibility + Screen Recording (two separate System Settings toggles).
E. Open CleanShot X → grant Screen Recording + Accessibility. If you have a license, paste it. Otherwise skip CleanShot, use Shottr (free).
F. Open 1Password → sign in to your existing account (or create one at 1password.com first)
→ Settings → Developer → check "Integrate with 1Password CLI" and "Touch ID" (so `op` CLI works)
G. Open OrbStack → enter your password on the Docker compatibility prompt → choose "Docker" mode.
H. Open Ice (`jordanbaird-ice`) — KNOWN BROKEN on Tahoe stable. Either skip, or download beta 0.11.13+ from github.com/jordanbaird/Ice/releases and install manually.
Phone-paired apps (you'll do at the very end, NOT now):
- WhatsApp / Signal / Telegram all need QR scans from your phone. Defer to Phase 8's final checklist.
Reply "done" when you've finished A-H. Skip anything you don't need.
============================================
5. After Piyush replies "done", verify the cask install:
```bash
brew list --cask | wc -l # should be >= 28
```
6. Print:
========================================
✅ PHASE 5 DONE — GUI apps installed, base perms granted
Proof:
- 28+ casks listed in `brew list --cask`
- cursor CLI works: `which cursor`
- 1Password CLI works: `op account list` returns your account
Pending (final checklist in Phase 8): phone-app QR scans, optional license keys.
Next: /clear, paste Phase 6.
========================================
Important
What this does: Wires Claude Code up with the best skills/plugins/MCPs for an AI/RAG developer: live docs lookup (Context7), web scraping (Firecrawl), Postgres queries, browser automation (Playwright), semantic code search (Serena), and more. Makes Claude much more powerful inside your projects. ~10 min.
You'll do: Generate a GitHub Personal Access Token at github.com/settings/tokens (Claude will tell you exactly what scopes to pick) + paste API keys for Firecrawl and Brave Search if you have them (both have free tiers — sign-up links provided).
Success looks like: claude mcp list shows 10+ servers connected (green ✓). Inside Claude, /mcp shows all servers ready.
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phase 5 done. Now do Phase 6: install Claude Code marketplaces, skills, and MCP servers.
BEFORE YOU START
1. Register todos.
2. Preflight: `which claude`, `which npx`, `which uvx` (skip Serena/time/fetch if uvx missing — but `brew install uv` should've handled it). STOP only if `claude` is missing.
THIS PHASE HAS 1-3 STOPS (API key prompts).
KEY FACTS (May 2026)
- `anthropics/claude-plugins-official` is PRE-REGISTERED — do NOT try to `marketplace add` it.
- `@modelcontextprotocol/server-github` is ARCHIVED — use GitHub's remote MCP with a PAT.
- `@modelcontextprotocol/server-brave-search` is ARCHIVED — use `@brave/brave-search-mcp-server`.
- Serena CANNOT be added via marketplace — must be `uv tool install` first.
STEPS
1. Add 2 useful marketplaces (skip if already added):
```bash
claude plugin marketplace add obra/superpowers-marketplace 2>/dev/null || true
claude plugin marketplace add shinpr/claude-code-workflows 2>/dev/null || true
```
2. Install first-party skills:
```bash
claude plugin install superpowers@claude-plugins-official
claude plugin install frontend-design@claude-plugins-official
```
superpowers bundles brainstorming + systematic-debugging + TDD + verification-before-completion automatically.
3. Install MCP servers — start with the ones that need NO API key:
```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$HOME/projects"
claude mcp add context7 -- npx -y @upstash/context7-mcp
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
claude mcp add playwright -- npx -y @playwright/mcp@latest
claude mcp add repomix -- npx -y repomix --mcp
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking
```
4. Install Serena (semantic code search — needs uv):
```bash
uv tool install -p 3.13 serena-agent
claude mcp add serena -- serena start-mcp-server
```
5. Install time + fetch + git MCPs (also via uvx):
```bash
claude mcp add time -- uvx mcp-server-time
claude mcp add fetch -- uvx mcp-server-fetch
```
6. GitHub MCP (needs a PAT) — STOP and ask:
🛑 GITHUB TOKEN
What: Open github.com/settings/tokens → Generate new token (classic)
Note: "claude-code-mcp" | Scopes: check `repo` + `read:org` + `workflow`
Generate → copy the token (ghp_...).
Then: Reply with the token (just paste it in chat).
Then run:
```bash
claude mcp add-json github "{\"type\":\"http\",\"url\":\"https://api.githubcopilot.com/mcp\",\"headers\":{\"Authorization\":\"Bearer <token>\"}}"
```
7. Firecrawl (optional but useful for RAG ingestion) — STOP and ask:
🛑 FIRECRAWL KEY (optional, skip if not interested)
What: Go to firecrawl.dev → sign up → copy your API key (starts with fc-)
Free tier: 500 scrapes/month — enough for trying.
Then: Paste key, or reply "skip".
```bash
FIRECRAWL_API_KEY=fc-... claude mcp add firecrawl -- npx -y firecrawl-mcp
```
8. Brave Search MCP (optional) — STOP and ask:
🛑 BRAVE SEARCH KEY (optional, skip if not interested)
What: Go to brave.com/search/api → free tier 2000 queries/month
Then: Paste key, or "skip".
```bash
BRAVE_API_KEY=... claude mcp add brave-search -- npx -y @brave/brave-search-mcp-server --transport stdio
```
9. Verify everything:
```bash
claude mcp list
```
Should show 8-11 servers, status green ✓. Red ✗ means restart Claude (Cmd+Q, re-run `claude`).
10. Tell Piyush about optional Nitya add-ons (don't install — just inform):
"If Nitya uses these tools, add the matching MCP later:
- Linear: claude mcp add --transport http linear https://mcp.linear.app/mcp
- Notion: claude mcp add --transport http notion https://mcp.notion.com/mcp
- Supabase: claude mcp add-json supabase '{\"type\":\"http\",\"url\":\"https://mcp.supabase.com/mcp\"}'
- Postgres: see claude-skills-install.sh in the gist for the Docker command
Each requires `/mcp` in Claude to complete OAuth."
11. Print:
========================================
✅ PHASE 6 DONE — Claude Code MCPs + skills wired
Proof:
- `claude mcp list` shows 8-11 servers (most green ✓)
- `claude plugin list` shows superpowers, frontend-design
Next: /clear, paste Phase 7.
========================================
Important
What this does: Flips a bunch of macOS settings that every developer wants (faster key repeat, show hidden files, kill smart-quotes that break code paste, screenshots-to-folder, hide the Dock instantly). Then installs your Cursor extensions for Python and TypeScript. ~3 min.
You'll do: Log out + log back in once at the end (needed to apply the key repeat change).
Success looks like: Holding j fills the screen with js in under a second (vs slow keyboard before).
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phase 6 done. Now do Phase 7: apply developer-friendly macOS defaults + install Cursor extensions.
BEFORE YOU START
1. Register todos.
2. No preflights needed — these are independent of prior phases.
NO STOPS in this phase. End by telling Piyush to log out / log in.
STEPS
1. Apply macOS defaults (these write directly to plists — no clicks needed):
```bash
# Finder: show hidden files + full path in title
defaults write com.apple.finder AppleShowAllFiles -bool true
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true
defaults write com.apple.finder ShowPathbar -bool true
defaults write com.apple.finder ShowStatusBar -bool true
# Faster key repeat (game-changer for coding)
defaults write -g KeyRepeat -int 2
defaults write -g InitialKeyRepeat -int 15
# Kill smart quotes / dashes / spelling correction (they break code paste)
defaults write -g NSAutomaticDashSubstitutionEnabled -bool false
defaults write -g NSAutomaticQuoteSubstitutionEnabled -bool false
defaults write -g NSAutomaticSpellingCorrectionEnabled -bool false
# Dock: auto-hide instantly, no recent apps
defaults write com.apple.dock autohide -bool true
defaults write com.apple.dock autohide-delay -float 0
defaults write com.apple.dock autohide-time-modifier -float 0.3
defaults write com.apple.dock show-recents -bool false
# Screenshots go to a dedicated folder (cleaner Desktop)
mkdir -p ~/Pictures/Screenshots
defaults write com.apple.screencapture location ~/Pictures/Screenshots
# Apply changes
killall Finder Dock SystemUIServer
```
2. Install useful Cursor extensions (if `cursor` CLI was installed in Phase 5):
```bash
if command -v cursor >/dev/null; then
cursor --install-extension ms-python.python
cursor --install-extension ms-python.vscode-pylance
cursor --install-extension dbaeumer.vscode-eslint
cursor --install-extension esbenp.prettier-vscode
cursor --install-extension bradlc.vscode-tailwindcss
cursor --install-extension ms-azuretools.vscode-docker
cursor --install-extension eamodio.gitlens
fi
```
3. Create a tidy project structure (purely optional — Piyush may already have his own):
```bash
mkdir -p ~/projects ~/Pictures/Screenshots
```
4. STOP banner — final manual step for this phase:
🛑 LOG OUT + LOG IN ONCE
What: The faster key repeat won't kick in until you log out + back in.
Apple Menu → Log Out — then log back in.
Then: Open a new Ghostty tab and try holding a key. Should be MUCH faster.
Reply "done"
5. Print:
========================================
✅ PHASE 7 DONE — macOS defaults + Cursor extensions
Proof:
- `defaults read -g KeyRepeat` = 2
- `defaults read com.apple.finder AppleShowAllFiles` = 1
- ~/Pictures/Screenshots exists
- cursor extensions installed (run `cursor --list-extensions` to see)
Next: /clear, paste Phase 8 (the verify-and-finish phase).
========================================
Important
What this does: Runs a health check across the whole install (verify.sh) and prints a final checklist of "stuff only you can do" — phone QR scans for messaging apps, sign-ins for cloud services, optional license keys. ~5 min.
You'll do: Work through the printed checklist on your own time.
Success looks like: verify.sh exits with "✅ All required items installed" and you have a clear todo list for the rest.
Copy ↓, paste into Claude:
You are helping Piyush set up his Mac. Phases 0-7 done. Now do Phase 8: run the verify script and print the final manual checklist.
STEPS
1. Download verify.sh from the gist:
```bash
curl -sSL https://gist.githubusercontent.com/Aboudjem/da6b37f5d58a9e8b1b238e11a860d3d3/raw/verify.sh -o /tmp/verify-piyush.sh
chmod +x /tmp/verify-piyush.sh
```
2. Run it and capture output:
```bash
bash /tmp/verify-piyush.sh
```
Show Piyush the full output.
3. If verify shows failures, ask Piyush whether to re-attempt the failing items now or defer (use AskUserQuestion):
- "Want me to re-run the missing installs now?" (yes / no / show me first)
4. Print the consolidated FINAL MANUAL CHECKLIST below — these are things Claude CANNOT do, Piyush has to:
========================================
🛑 FINAL MANUAL CHECKLIST — your turn
(Estimate: 30-45 min total, do at your own pace)
PHONE-PAIRED APPS (need your phone)
[ ] WhatsApp → on phone: Settings → Linked Devices → Link a Device → scan QR on Mac
[ ] Signal → on phone: Settings → Linked Devices → + → scan QR on Mac
[ ] Telegram → enter phone number, approve from existing Telegram session on phone
APP SIGN-INS (browser/OAuth)
[ ] Notion → sign in to your Nitya workspace
[ ] Notion Calendar → sign in WITH GOOGLE (Google account required — no other auth supported)
[ ] Slack → sign in to each Nitya workspace (separate browser flow each)
[ ] Zoom → sign in
[ ] Brave / Chrome / Firefox → sign in to sync (optional)
[ ] Cursor → sign in (only needed for Pro features — skip if free tier)
[ ] Postman → sign in (optional)
CLI CREDENTIALS (you'll need access keys)
[ ] `aws configure` — paste your AWS access key + secret + region (ask Nitya admin if unsure)
[ ] `doctl auth init` — paste DigitalOcean token (only if Nitya uses DO)
[ ] `op signin` — verify 1Password CLI works (the desktop app needs CLI integration ON — see Phase 5 step F)
LICENSE KEYS (optional paid apps)
[ ] CleanShot X — buy at cleanshot.com if you want it past the trial
[ ] TablePlus — free tier limited to 2 tabs; license at tableplus.com for more
[ ] Cursor Pro — $20/mo, optional, unlocks Composer + Agent
[ ] Raycast Pro — $8/mo, unlocks AI commands (skip if you have ChatGPT/Claude already)
KNOWN-BROKEN ON TAHOE
[ ] Ice menubar app — the brew cask is broken. Either skip, or grab beta 0.11.13+ from
github.com/jordanbaird/Ice/releases (manual download).
PERMISSION RE-PROMPTS (macOS Tahoe re-prompts these MONTHLY)
[ ] Every month, macOS will re-prompt for Accessibility / Screen Recording on:
Raycast, Rectangle, AltTab, CleanShot, Zoom. Just re-grant.
BACKUPS / DOTFILES
[ ] Consider committing your `~/.zshrc`, `~/.gitconfig`, `~/.config/ghostty/config`,
`~/.claude/settings.json` to a private GitHub repo so you can restore on any new Mac.
========================================
5. Print final message:
========================================
✅ PHASE 8 DONE — install complete
Total install time: ~75 min Claude work + ~30 min your interactive time
You now have:
- Modern terminal (Ghostty + premium config + notification hooks)
- Smart shell (oh-my-zsh + Starship + autosuggest + syntax highlighting)
- Node + Python pinned via mise
- GitHub SSH auth + git config
- 33+ modern CLI tools (eza, bat, rg, fzf, lazygit, jq, mise, uv, ollama, ...)
- 28+ GUI apps (Cursor, Brave, Raycast, 1Password, Obsidian, Notion, Slack, ...)
- Claude Code wired with 8-11 MCPs + superpowers + frontend-design
- Dev-friendly macOS defaults
Work through the final manual checklist when you have time.
Welcome to your new Mac. 🚀
========================================
Warning
If a phase fails halfway and you want to restart it, just paste the same prompt again. Claude will detect what's already done (via the preflight checks) and pick up where it left off.
| Symptom | Fix |
|---|---|
command not found: brew |
Re-run eval "$(/opt/homebrew/bin/brew shellenv)". Verify which brew returns /opt/homebrew/bin/brew. |
command not found: npm or node |
Mise didn't activate. Open new tab, or eval "$(mise activate zsh)". |
claude mcp list shows red ✗ on a server |
Restart Claude (Cmd+Q, re-run claude). MCPs initialize on Claude startup. |
| Permission prompts keep coming back | macOS Tahoe re-prompts monthly. Annoying but normal — just re-grant. |
| Ghostty looks wrong (boxes for icons) | The JetBrains Mono Nerd Font cask installed but Ghostty was open — Cmd+Q Ghostty and re-open. |
| Spotlight still steals Cmd+Space from Raycast | System Settings → Keyboard → Keyboard Shortcuts → Spotlight → uncheck both. Logout/login. |
| oh-my-zsh subshell trap (terminal hangs) | Use the install with RUNZSH=no CHSH=no env vars — Phase 2 already does this. |
- Ghostty — fastest Mac terminal, native AppKit, the new consensus pick in 2026.
- oh-my-zsh — beginner-friendly framework, well-documented, huge plugin ecosystem.
- Starship — modern cross-shell prompt, much lighter than Powerlevel10k.
- mise — one tool to manage Node + Python + Rust + Go versions (replaces nvm + pyenv + ...).
- uv — Astral's Python tool, 10-100x faster than pip, absorbed Rye in Feb 2026.
- Cursor — VS Code with AI built in; pairs with Claude Code (Cursor for inline, Claude for multi-file).
- Brave — Chromium with native ad/tracker block, fewer extensions to manage than Chrome.
- Raycast — replaces Spotlight + Alfred + clipboard managers in one launcher.
- Rectangle — free window snapping; minimal, doesn't fight with macOS.
- 1Password — gold-standard password manager + secrets injection via
opCLI. - OrbStack — 10× lighter than Docker Desktop, same
dockerCLI. - TablePlus — fast Postgres GUI, handles pgvector for Nitya's RAG dev.
Stack curated by Adam Boudjemaa. Verified May 2026 against formulae.brew.sh, official MCP repos, and live Ghostty/Claude Code docs. Bug reports / improvements → ping Adam on Slack.