# Homebrew Dev Machine Setup

> Bootstrap or verify a macOS Homebrew-based software engineering workstation, especially Apple Silicon home-lab machines. Use when Codex is asked to install global developer tooling such as Python, Node/npm, pnpm, yarn, pipx, uv, Git/GitHub CLI, jq/yq, ripgrep/fd/fzf, build tools, or to check that a newly configured Mac did not add services, global package surprises, or obvious backdoor-like background agents.

- Skill: `careylzh/homebrew-dev-machine-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add careylzh/homebrew-dev-machine-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/careylzh/homebrew-dev-machine-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: careylzh (https://skillmd.com/u/careylzh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/careylzh/homebrew-dev-machine-setup

---


# Homebrew Dev Machine Setup

## Overview

Set up a pragmatic global developer baseline on macOS using Homebrew, then verify command resolution, versions, package-manager state, and obvious background-service side effects.

Be explicit about the security boundary: this workflow can check package-manager hygiene and obvious launch/service registrations, but it cannot prove the whole computer has no vulnerabilities or spyware.

## Workflow

1. Inspect the machine first.

```sh
uname -m
which brew
which python3
which node
which npm
```

Prefer `/opt/homebrew` on Apple Silicon. If Homebrew is missing, ask before installing it because that requires network access and may require sudo.

2. Update Homebrew metadata.

```sh
brew update
```

If the environment reports restricted network access or sandbox denial, rerun with the appropriate user approval rather than trying to work around it.

3. Install the baseline.

```sh
brew install python node pnpm yarn pipx uv git gh jq yq ripgrep fd fzf tree wget curl cmake pkg-config openssl@3 readline sqlite xz zlib
```

Notes:

- `node` supplies `npm`.
- `pkg-config` may appear as `pkgconf` in Homebrew output; this is expected.
- `curl` and `zlib` are keg-only on macOS; do not force-link them unless the user specifically needs Homebrew versions first in PATH.

4. Fix shell command resolution when needed.

Run `brew doctor` and read PATH warnings. If a framework Python or `/usr/bin` shadows Homebrew tools, update `~/.zprofile` conservatively:

```sh
eval "$(/opt/homebrew/bin/brew shellenv)"
export PATH="/opt/homebrew/opt/python@3.14/libexec/bin:$PATH"
```

Use the installed Homebrew Python version in the path if it differs from `python@3.14`.

5. Verify in a fresh shell.

```sh
zsh -lc 'which python python3 pip pip3 git jq node npm pnpm yarn uv pipx gh cmake && python --version && python3 --version && pip --version && git --version && jq --version && node --version && npm --version && pnpm --version && yarn --version && uv --version && pipx --version && gh --version | head -n 1 && cmake --version | head -n 1'
```

6. Check package-manager and background-service hygiene.

```sh
brew doctor
brew services list
brew outdated
brew leaves
npm list -g --depth=0
pipx list
zsh -lc 'python -m pip list --format=columns'
ls -la ~/Library/LaunchAgents
ls -la /Library/LaunchDaemons /Library/LaunchAgents
```

Do not use `npm audit -g` as a global audit signal; npm reports that global audits are unsupported.

7. Handle admin-only repairs honestly.

If `brew doctor` reports `/opt/homebrew` ownership or `Caskroom` writability problems, the practical fix requires sudo:

```sh
sudo chown -R "$USER" /opt/homebrew /opt/homebrew/Caskroom
```

Only run sudo with explicit user approval. If the prompt requires an interactive password and the user does not enter it, cancel the waiting session and report that this item remains unresolved.

If `brew doctor` reports broken Command Line Tools quarantine support, recommend:

```sh
xcode-select --install
```

Do not run destructive CLT removal commands unless the user explicitly asks.

## Reporting

Summarize:

- installed or already-present formulae
- final versions and command paths from a fresh shell
- Homebrew services status
- global npm, pip, and pipx state
- LaunchAgent/LaunchDaemon findings that are relevant to the setup
- unresolved admin-only work

Avoid claiming the machine has no security vulnerabilities. Say what was checked and what those checks can and cannot establish.