omc-mac-setup

An interactive, preset-driven macOS bootstrapper for developers. Installs CLI tools, editors, browsers, and system preferences via Homebrew — with idempotent checks, configurable profiles, and graceful failure handling.

Built for React Native developers, but works for any macOS dev setup.

Quick Start

# Interactive mode — pick a preset, choose your tools
npx omc-mac-setup

# Non-interactive — full React Native setup
npx omc-mac-setup --preset react-native

# See what would happen without installing anything
npx omc-mac-setup --preset react-native --dry-run

Presets

Pick a preset to control what gets installed. After selecting a preset, you can still add or remove individual tools in interactive mode.

| Preset | What's included | Use case | |--------|----------------|----------| | minimal | Git, CLI tools, shell | Keep your machine lean | | frontend | CLI + dev tools + apps | General frontend development | | react-native | Everything | Full RN environment with Android Studio, JDK, CocoaPods | | custom | You pick | Category-by-category selection |

npx omc-mac-setup --preset minimal
npx omc-mac-setup --preset frontend
npx omc-mac-setup --preset react-native

What Gets Installed

Every tool has a level: required (auto-installed), recommended (pre-checked), or optional (unchecked, shown in list).

Git & SSH

| Tool | Level | What it does | |------|-------|-------------| | git | recommended | Version control | | SSH key (ed25519) | recommended | GitHub authentication |

Configures git config --global for name and email after install.

CLI Tools

Modern Rust-powered replacements for classic Unix utilities.

| Tool | Level | Replaces | What it does | |------|-------|----------|-------------| | eza | recommended | ls, tree | Colors, icons, tree view | | bat | recommended | cat | Syntax highlighting + git integration | | fd | recommended | find | Fast file search | | ripgrep | recommended | grep | Blazing fast text search | | fzf | recommended | — | Fuzzy finder for everything | | jq | recommended | — | JSON processor | | gh | recommended | — | GitHub CLI — PRs, issues, actions | | delta | recommended | diff | Beautiful git diffs | | lazygit | recommended | — | Git terminal UI | | lazydocker | optional | — | Docker terminal UI | | zoxide | recommended | z, cd | Smart directory jumping | | tldr | recommended | man | Simplified man pages | | direnv | optional | — | Per-directory env vars | | atuin | optional | — | Shell history search | | httpie | optional | curl | Modern HTTP client |

Removed from the original script: z (use zoxide), thefuck (slow startup), tree (use eza --tree), wget (curl built-in), trash, git-extras (gh covers it).

Dev Tools

| Tool | Level | What it does | |------|-------|-------------| | node | required | Node.js runtime (needed for Metro/Expo) | | bun | required | Primary JS runtime + package manager (bun install, bunx) | | pnpm | optional | Alternative package manager | | tmux | recommended | Terminal multiplexer — split panes, persistent sessions |

Removed: yarn (use bun), fnm/nvm (direct node install, bun handles the rest), typescript global (project-local).

AI Tools

| Tool | Level | What it does | |------|-------|-------------| | ollama | optional | Run LLMs locally (llama, codellama, mistral) | | claude-code | optional | Anthropic's AI coding agent (native installer) |

Claude Code requires an Anthropic account ($20+/mo). Installed via native installer, not npm.

React Native

Skip this entire category for lean machines. Only included in the react-native preset.

| Tool | Level | What it does | |------|-------|-------------| | watchman | required | File watcher for Metro bundler | | zulu@17 | required | Java Development Kit for Android builds | | android-studio | required | Android IDE and SDK manager | | cocoapods | required | iOS dependency manager (via gem install) | | fastlane | recommended | Build/deploy automation | | eas-cli | recommended | Expo Application Services CLI | | Android SDK env vars | required | ANDROID_HOME, JAVA_HOME, PATH |

Removed: expo-cli (deprecated — use npx expo), @react-native-community/cli (bundled with RN), ruby (system ruby works).

Note: CocoaPods is deprecating new podspecs after December 2, 2026. Migration to Swift Package Manager is coming.

Applications

GUI apps are prompted separately: "Install GUI apps? (y/N)" — not part of the default CLI-only flow.

Core

| App | Level | What it does | |-----|-------|-------------| | Antigravity | recommended | Google account sign-in | | Ghostty | recommended | Fast, native macOS terminal | | Warp | optional | AI-powered terminal | | VS Code | recommended | Code editor | | Cursor | optional | AI editor ($20/mo) | | OrbStack | recommended | Docker replacement — 2s startup, 60% less RAM | | Bruno | recommended | Git-friendly API client (replaces Postman) |

Browser, Utilities, Communication, Media

| App | Level | |-----|-------| | Google Chrome | recommended | | Raycast | recommended | | 1Password | optional | | Rectangle | optional | | MonitorControl | optional | | Slack | optional | | Notion | optional | | Spotify | optional | | VLC | optional | | Figma | optional |

Removed: Postman (use Bruno), CleanMyMac (bloatware), iTerm2 (use Ghostty), Docker Desktop (use OrbStack), Arc, Zed, Discord, Zoom, Firefox.

Shell Setup

| Tool | Level | What it does | |------|-------|-------------| | Oh My Zsh | recommended | Zsh framework | | zsh-syntax-highlighting | recommended | Fish-like syntax highlighting | | zsh-autosuggestions | recommended | Fish-like autosuggestions | | Starship | recommended | Cross-shell prompt (Rust, fast) |

macOS Defaults

Safe defaults (single confirmation):

• Dock: auto-hide with zero delay, 42px icons
• Finder: show extensions, column view, no .DS_Store on network
• Keyboard: fast repeat rate, disable autocorrect/capitalization/smart quotes
• Screenshots: save to Desktop as PNG
• Safari: enable developer tools

Risky defaults (double confirmation with security warning):

• Disable Gatekeeper (allow apps from anywhere)
• Map Caps Lock to Escape (via hidutil + LaunchAgent)

CLI Flags

npx omc-mac-setup                           # Interactive mode
npx omc-mac-setup --preset <name>           # Non-interactive preset
npx omc-mac-setup --preset <name> --dry-run # Preview without installing
npx omc-mac-setup --category cli-tools,apps # Install specific categories
npx omc-mac-setup --dry-run                 # Dry run (needs preset or non-TTY)

Dotfile Strategy

The tool never appends directly to ~/.zshrc. Instead:

1. All shell init lines are written to ~/.omc-mac-setup.zsh
2. A single source line is added to .zshrc (with duplicate detection):

   # omc-mac-setup
   [ -f ~/.omc-mac-setup.zsh ] && source ~/.omc-mac-setup.zsh

3. If a dotfile manager is detected (chezmoi, stow, yadm), it warns you and prints the source line to add manually.

Re-running the tool cleanly overwrites ~/.omc-mac-setup.zsh — no duplicates, no conflicts.

Idempotency

Safe to run multiple times. Every tool checks if it's already installed before attempting installation. Already-installed tools are skipped and reported in the summary.

Uninstall

All tools are installed via Homebrew. To undo:

# CLI tools
brew remove <name>

# GUI apps
brew uninstall --cask <name>

# Shell config
rm ~/.omc-mac-setup.zsh
# Then remove the source line from ~/.zshrc

Logging

Every run appends to ~/.omc-mac-setup.log with timestamps. The summary at the end shows:

• Installed — what was newly installed
• Skipped — what was already present
• Failed — what errored (install continues past failures)
• Manual steps — what needs post-install attention (Android Studio SDK, app sign-ins, etc.)

Architecture

src/
├── index.ts              # CLI entry: args, presets, install loop, summary
├── types.ts              # Tool, Category, Preset, InstallReport types
├── utils/
│   ├── shell.ts          # Shell command execution
│   ├── brew.ts           # Homebrew install/check operations
│   ├── checks.ts         # Platform detection, dotfile manager detection
│   └── logger.ts         # Install tracking + log file
└── categories/
    ├── git-setup.ts      # Git + SSH
    ├── cli-tools.ts      # 15 modern CLI tools
    ├── dev-tools.ts      # Node, Bun, tmux
    ├── ai-tools.ts       # Ollama, Claude Code
    ├── react-native.ts   # Watchman, JDK, Android Studio, CocoaPods
    ├── apps.ts           # 17 GUI apps
    ├── shell-setup.ts    # Oh My Zsh, Starship, shell init
    └── macos-defaults.ts # Safe + risky system preferences

Built with TypeScript, @clack/prompts for the interactive UI, and tsup for bundling into a single 32KB file.

Requirements

• macOS 13.0+ (Ventura or later)
• Apple Silicon (arm64) or Intel (x86_64)
• Node.js 20+

License

MIT