Initial Setup (Mac)

Install the required tools on your Mac and verify your development environment.

💻 Using Windows? See Initial Setup (Windows).

Install Claude Code

In vibe coding, you build by giving instructions to Claude Code — the Claude that reads and writes the files on your machine and runs commands for you. Even the setup steps on this page are written to be handed to Claude Code rather than typed out by hand, so install it first.

The easiest way to get Claude Code is the Claude desktop app:

Download: Get the Mac app from claude.com/download
Install: Open the downloaded file and move the app to your Applications folder
Log in: Launch the app and log in with your Claude account (contact an admin if you don't have one — Claude Code requires a paid plan)
Open the Code tab: Claude Code is the Code tab at the top of the app. Open it and choose Local so Claude works with the files on your own machine. Select folder points it at a project — you will point it at this repository once you clone it further down this page.

The desktop app includes Claude Code, so there is nothing else to install for it.

Prefer the terminal? Claude Code is also a command-line tool. Install it with brew install --cask claude-code, then run claude inside your project folder. It is the same Claude Code and shares your settings and CLAUDE.md files with the app.

The "Ask Claude" prompts throughout this guide are written to be pasted into Claude Code.

Prerequisites Checklist

Before you start vibe coding, make sure you have these tools installed:

Tool	Purpose	Required
Claude Code	Does the work in this guide (Claude desktop app, or the `claude` CLI)	✅ Yes
Homebrew	Package manager for macOS	✅ Yes
Node.js	JavaScript runtime	✅ Yes
pnpm	Fast package manager	✅ Yes
Git	Version control	✅ Yes
Git LFS	Large file storage for Git	✅ Yes
GitHub CLI (gh)	Create PRs from terminal	✅ Yes

Verify Your Installation

Already have some tools installed? Check which ones you need:

Ask Claude to verify your setup

Claude prompt

Check if all the required development tools are installed on my machine: - Homebrew - Node.js (v20+) - pnpm - Git - Git LFS (git-lfs) - GitHub CLI (gh) Show me the version of each tool. If any tool is not installed, use Claude Code to install it for me.

Or run it yourselfbash

# Check all versions
echo "Homebrew: $(brew --version | head -1)"
echo "Node.js: $(node --version)"
echo "pnpm: $(pnpm --version)"
echo "Git: $(git --version)"
echo "Git LFS: $(git lfs version)"
echo "GitHub CLI: $(gh --version | head -1)"

Expected Output

You should see version numbers for each tool:

Expected outputtext

Homebrew: Homebrew 4.x.x
Node.js: v20.x.x
pnpm: 9.x.x
Git: git version 2.x.x
Git LFS: git-lfs/3.x.x (GitHub; darwin arm64; go 1.x.x)
GitHub CLI: gh version 2.x.x

If any tool shows "command not found", follow the installation guide below.

Installation Guide

1. Install Homebrew

Homebrew is the package manager for macOS. Open Terminal and run:

Install Homebrewbash

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

After installation, follow the instructions to add Homebrew to your PATH.

2. Install Node.js

We recommend using Node.js version 20 or later:

Install Node.js via Homebrewbash

brew install node@20

# Or install the latest LTS version
brew install node

3. Install pnpm

pnpm is our package manager of choice for the monorepo. Global npm packages require sudo:

Install pnpmbash

sudo npm install -g pnpm

Why sudo? Global npm packages are installed in a system directory that requires administrator permissions. This is safe for trusted packages like pnpm.

4. Install Git

Git is usually pre-installed on macOS, but you can update it:

Install/Update Gitbash

brew install git

5. Install GitHub CLI

The GitHub CLI (gh) allows Claude to create Pull Requests directly:

Install GitHub CLIbash

brew install gh

# Then authenticate with your GitHub account
gh auth login

When running gh auth login, choose:

GitHub.com
HTTPS
Authenticate with a web browser

6. Install Git LFS

Git LFS (Large File Storage) is required for handling large binary files in the repository:

Install Git LFSbash

brew install git-lfs

# Initialize Git LFS for your user account
git lfs install

After running git lfs install, you should see:

Expected outputtext

Git LFS initialized.

Clone the Repository

Once all tools are installed, clone the repository:

Ask Claude to clone the repo

Claude prompt

Clone the vibe-coding-platform-foundation repository from https://github.com/CoworkingKitchen/vibe-coding-platform-foundation and install dependencies.

Or run it yourselfbash

# Clone the repository
git clone [email protected]:CoworkingKitchen/vibe-coding-platform-foundation.git

# Navigate to the directory
cd vibe-coding-platform-foundation

# Install all dependencies
pnpm install

Setup Quiz

Quiz

Which command should you use to install dependencies in this monorepo?

npm installyarn installpnpm installbun install

Troubleshooting

"command not found: brew"

Add Homebrew to your PATH. For Apple Silicon Macs:

Add Homebrew to PATHbash

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

"gh: command not found" after installation

Restart your terminal or run:

Reload shell configurationbash

source ~/.zshrc

"Permission denied" errors with npm global install

Use sudo for global npm package installations:

Install with sudobash

sudo npm install -g pnpm

Next Steps

Once your setup is complete, proceed to the Workflow to start your first contribution.