AI Dev Bootstrap for Mac

Set up your Mac for vibe-coding with AI in minutes.

✨ What is this?

AI Dev Bootstrap for Mac is an interactive installer that prepares a brand‑new or existing Mac for building apps and automations with AI coding tools like OpenCode. It’s designed for non‑technical users, with guided prompts and safe defaults. You can run it multiple times — it only installs what’s missing and skips what you already have.

✅ Requirements

• macOS 15 (Sequoia) or newer
• Apple Silicon or Intel Mac
• Internet connection for downloading installers
• Git for the manual clone option below. If Git is missing, macOS will offer to install the Xcode Command Line Tools when you run the installer.

⚡ Quick Start

You have two ways to install. Pick whichever you prefer — they end up at the same place.

One‑liner (recommended):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/skwid138/ai-dev-bootstrap-mac/main/install.sh)"

This downloads a small setup script that copies this project (the “repo,” short for repository) into ~/code/ai-dev-bootstrap-mac and then runs the installer. If Git is missing, macOS will offer to install the Xcode Command Line Tools first.

To pass flags through the one‑liner, add -s -- and your flags after the closing paren:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/skwid138/ai-dev-bootstrap-mac/main/install.sh)" -s -- --dry-run

Or clone the repo yourself:

mkdir -p ~/code
git clone https://github.com/skwid138/ai-dev-bootstrap-mac.git ~/code/ai-dev-bootstrap-mac
~/code/ai-dev-bootstrap-mac/bootstrap.sh

Either way, the repo lives at ~/code/ai-dev-bootstrap-mac afterward and you can re‑run bootstrap.sh (or just ./bootstrap.sh --launcher-only) any time.

📦 Install Tiers

Install tiers are bundles of tools. Start with Recommended if you are unsure; choose Custom if you want to pick tools one by one.

Tier	Packages	What you get	Key tools
Essential	14	Minimum setup for AI‑assisted dev	Xcode CLT, Homebrew, Bash 5, Git, VS Code, Node, Python, OpenCode
Recommended	+10	Quality‑of‑life upgrades	Ghostty, tmux, direnv, zplug, Spaceship prompt, zsh plugins
Complete	+7	Power‑user extras	Ollama or LM Studio, OrbStack, Playwright, ffmpeg

Want more control? Choose Custom in the installer and pick exactly what you want.

📋 What Gets Installed

Essential (14 packages)

• Xcode Command Line Tools — Build tools and system git
• Homebrew — Package manager
• Bash — Modern bash 5.x (macOS ships 3.2)
• Gum — Interactive terminal UI
• Git — Version control
• GitHub CLI (gh) — GitHub auth and repo tools
• VS Code — Code editor
• mise — Runtime version manager
• Node.js LTS — JavaScript runtime (via mise)
• uv — Python package manager
• Python — Python runtime (via uv)
• ripgrep (rg) — Fast file search
• jq — JSON processor
• OpenCode — AI coding tool

Recommended (Essential + 10)

• Ghostty — Modern terminal emulator
• fd — Friendly find replacement
• direnv — Per‑folder environment variables
• tmux — Terminal multiplexer
• btop — System resource monitor
• zplug — Zsh plugin manager
• Spaceship prompt — Clean, informative prompt
• zsh-syntax-highlighting — Command highlighting
• zsh-autosuggestions — History‑based suggestions
• (All Essential packages)

Complete (Recommended + 7)

• Ollama — Local AI models
• LM Studio — Local AI desktop app
• OrbStack — Lightweight containers & Linux VMs
• Playwright — Browser automation
• shfmt — Shell formatter
• ffmpeg — Media processing
• ImageMagick — Image processing
• (All Recommended packages)

🧭 How It Works

1. Preflight checks for macOS version, Mac chip type, and disk space.
2. Tier selection (Essential, Recommended, Complete, or Custom).
3. Safe re-runs — already‑installed tools are skipped, so you can run the installer again later.
4. Terminal startup setup with small, organized shell files.
5. OpenCode AI provider setup with guided prompts for the account or API key OpenCode should use.
6. Summary of what was installed, skipped, or failed.

💬 What Working With OpenCode Looks Like

The bootstrap configures OpenCode to behave like a careful project manager — not a code-spitting machine. The goal: you describe what you want in plain English, the AI figures out whether it's a small thing or a big thing, and you stay in the driver's seat for every change.

For small, obvious requests ("fix this typo", "rename this variable") the AI confirms it understood you, shows the change it wants to make, and waits for your "yes" before touching the file. No ceremony — just a quick approval before any edit lands.

For bigger requests ("build me a Mac app that reminds me to drink water") the AI takes a slower path:

1. Asks clarifying questions — usually multiple-choice, with a recommended default — so it understands what you actually want.
2. Writes a plan in plain language to a file under .project-plans/ so you can read it, push back, and resume the work later if needed.
3. Has a second AI audit the plan for risks, missing pieces, and bad assumptions. The audit findings are shown to you (even if there were none).
4. Asks if you want to build it before writing any code.
5. Builds in small, reviewable steps instead of dropping a wall of code at once.

You can approve, push back, or change direction at any step. Destructive commands (rm -rf, force-pushing to git, system-level tools) are blocked at the OpenCode permission layer regardless — so even an over-eager AI can't accidentally wreck your machine.

If you want the deep technical details of how this is wired up, see opencode/README.md inside this repo.

🐷 JustVibes Launcher

If you install the Recommended tier (or higher), the bootstrap drops a one‑click app called JustVibes into your ~/Applications folder.

Open it from Spotlight, Launchpad, or Finder — drag it to your Dock for one‑click access. It opens Ghostty in your saved workspace folder and starts OpenCode automatically. No commands to remember.

Fresh every time. JustVibes always opens a single window with a single tab running OpenCode, regardless of what Ghostty had open last time. macOS would normally restore your previous Ghostty windows on launch; JustVibes suppresses that just for itself so the experience stays predictable. One side effect: if you open extra tabs inside a JustVibes window and then quit Ghostty (Cmd+Q), those extra tabs won't come back the next time you click JustVibes. Manual Spotlight/Dock launches of Ghostty are unaffected — they restore normally.

Branded identity, two things to quit. JustVibes shows up as JustVibes (with a piggy-bank icon) in your Dock, Cmd-Tab switcher, and Activity Monitor — distinct from Ghostty. The launcher and the terminal are two separate processes by design: this is what lets the launcher have its own identity. The trade-off is that quitting JustVibes (Cmd+Q from its Cmd-Tab card or right-click → Quit on the Dock tile) does not quit the Ghostty window it spawned, and vice versa. Quit them separately.

Cmd-Tab focuses the terminal. When JustVibes is already running, Cmd-Tabbing to its card (or clicking its Dock tile) brings the most recently spawned Ghostty terminal window forward — no need to Cmd-Tab past JustVibes to find Ghostty's card. The first time this happens after install, macOS may show a one-time Accessibility prompt asking to allow JustVibes to control "System Events"; click Allow. Saying no is fine — Cmd-Tabbing to JustVibes will just launch a fresh terminal instead of focusing the existing one.

Want to disable PID tracking entirely (and always get a fresh terminal on Cmd-Tab)? Set this in your shell:

export JUSTVIBES_TRACK_GHOSTTY_PID=0

Want a plain shell instead? Open Terminal or Ghostty directly. JustVibes is purely a convenience launcher; it doesn't change anything else on your system.

🐚 Shell Configuration

This project uses small shell startup files stored in:

~/.config/ai-bootstrap/shell/

Your existing ~/.zshenv, ~/.zprofile, and ~/.zshrc are never replaced. Three small, guarded blocks are appended (one per file) so you can remove them at any time:

# ai-bootstrap
[[ -f ~/.config/ai-bootstrap/shell/init_env.zsh ]] && source ~/.config/ai-bootstrap/shell/init_env.zsh

# ai-bootstrap
[[ -f ~/.config/ai-bootstrap/shell/init_profile.zsh ]] && source ~/.config/ai-bootstrap/shell/init_profile.zsh

# ai-bootstrap
[[ -f ~/.config/ai-bootstrap/shell/init_rc.zsh ]] && source ~/.config/ai-bootstrap/shell/init_rc.zsh

Shell startup layers

Zsh runs three different startup files depending on how a terminal or script is opened, and each one has a different job. The installer mirrors that split so the right things load at the right time:

• init_env.zsh (loaded by ~/.zshenv) — runs in every zsh, including background scripts. Sets up PATH, the list of folders your Mac searches for commands. Stays silent and fast so scripts and editor integrations aren't slowed down.
• init_profile.zsh (loaded by ~/.zprofile) — runs in login shells, such as your first terminal after logging in. Re‑applies PATH after macOS adjusts it, and activates tools like mise that need login-shell context.
• init_rc.zsh (loaded by ~/.zshrc) — runs in interactive shells, meaning terminals you actually type into. Loads zsh plugins (zplug), the Spaceship prompt, command highlighting, suggestions, and quality‑of‑life aliases.

Each block is guarded so it does not load twice, and PATH updates are safe to repeat. Re‑running the installer or having extra shell files around should not break anything.

Manual API Key Setup (OpenCode Go/Zen)

If you chose OpenCode Go/Zen and need to add or rotate your API key:

1. Visit https://opencode.ai and sign in
2. Navigate to the Zen tab
3. Click Copy Key
4. Run in Terminal:

security delete-generic-password -s 'opencode-api-key' -a "$USER" 2>/dev/null
security add-generic-password -s 'opencode-api-key' -a "$USER" -w "$(pbpaste)"

The key will be loaded automatically on your next terminal session or JustVibes launch. Using pbpaste keeps the key out of your shell history.

🛠 Troubleshooting

A CLI tool stopped working after brew upgrade (or after a long time without re‑running bootstrap). Run:

~/code/ai-dev-bootstrap-mac/bootstrap.sh --refresh-paths

This re‑bakes Homebrew's prefix paths into your shell config without touching anything else.

Want to check whether your paths are stale without making changes?

~/code/ai-dev-bootstrap-mac/bootstrap.sh --check-paths

Exits 0 if paths are healthy, non‑zero if they look stale.

🔁 Re‑running

Safe to run again anytime. The installer skips what you already have and can add new tools later (for example, upgrading from Essential to Recommended).

⬆️ Updating

To get the latest AI skills, commands, helper scripts, OpenCode settings, and JustVibes launcher updates without repeating the full installer prompts, run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/skwid138/ai-dev-bootstrap-mac/main/install.sh)" -s -- --update

The update path uses your saved tier and workspace. It refreshes managed OpenCode assets, overwrites helper scripts, preserves your current OpenCode model setting, re-runs the shell configuration module, and rebuilds JustVibes only when the launcher files changed. Module 10 may install shell config dependencies like zplug if selected in your tier.

Inside OpenCode, you can also ask “am I up to date?” or run:

/check-updates

After an update, quit and reopen JustVibes so OpenCode loads the latest skills, commands, and instructions.

🧪 Running Tests

brew install bats-core && bats tests/

🗂️ Project Structure

ai-dev-bootstrap-mac/
├── bootstrap.sh          # Main entry point — the installer
├── install.sh            # One-liner bootstrapper (curl target)
├── lib/                  # Shared shell helpers
├── modules/              # Install modules (one per tool/feature)
├── config/               # Package definitions and tier mappings
├── dotfiles/             # Modular zsh configuration files
├── ghostty/              # Ghostty terminal config and themes
├── launcher/             # JustVibes app bundle and build scripts
├── opencode/             # OpenCode AI config (agents, skills, commands)
├── scripts/              # Helper scripts for OpenCode self-maintenance
├── tests/                # Bats test suite
├── CONTRIBUTING.md       # Development guide and quality gates
└── README.md

🎨 Credits

• JustVibes app icon: Lucide piggy-bank (ISC License). See THIRD_PARTY_LICENSES.md.

📄 License

MIT