Bootspring
HomeGet Started

macOS Setup Guide

Complete guide to installing and configuring Bootspring on macOS.

System Requirements#

RequirementMinimumRecommended
macOS10.15 Catalina13 Ventura+
ProcessorIntel or Apple SiliconApple Silicon
Memory4 GB RAM8 GB RAM
Disk500 MB1 GB
Node.jsv18.0.0v20.x LTS

Installation Methods#

Method 1: Homebrew (Recommended)#

The easiest way to install on macOS:

1# Install Homebrew if needed 2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 3 4# Install Node.js 5brew install node 6 7# Install Bootspring 8npm install -g bootspring 9 10# Verify 11bootspring --version

Method 2: npm Direct#

If you already have Node.js:

npm install -g bootspring

Method 3: nvm (Version Management)#

For managing multiple Node.js versions:

1# Install nvm 2curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash 3 4# Restart terminal or source profile 5source ~/.zshrc 6 7# Install Node.js LTS 8nvm install --lts 9nvm use --lts 10 11# Install Bootspring 12npm install -g bootspring

Shell Configuration#

Zsh (Default on macOS)#

Add to ~/.zshrc:

1# Bootspring completions 2if command -v bootspring &> /dev/null; then 3 eval "$(bootspring completions zsh)" 4fi 5 6# Aliases (optional) 7alias bs="bootspring" 8alias bsg="bootspring generate" 9alias bsa="bootspring agent invoke"

Apply changes:

source ~/.zshrc

Bash#

Add to ~/.bash_profile:

# Bootspring completions if command -v bootspring &> /dev/null; then eval "$(bootspring completions bash)" fi

Apply changes:

source ~/.bash_profile

Authentication#

Browser Login#

bootspring login

This opens your default browser for authentication.

Device Code (Headless)#

For remote sessions or terminals without browser access:

bootspring login --device

Follow the instructions to enter the code at bootspring.dev/device.

API Key Authentication#

For CI/CD environments:

export BOOTSPRING_API_KEY="bs_live_xxx" bootspring status

Add to ~/.zshrc for persistence:

echo 'export BOOTSPRING_API_KEY="bs_live_xxx"' >> ~/.zshrc

Project Setup#

Initialize New Project#

cd ~/Projects/my-app bootspring init

Interactive Setup#

bootspring init --interactive

Walks you through:

  1. Project type selection
  2. Framework detection
  3. Agent configuration
  4. Context generation

Quick Setup#

bootspring init --yes

Uses defaults based on detected project structure.

Claude Desktop Integration#

Install Claude Desktop#

  1. Download from claude.ai/download
  2. Install the application
  3. Sign in with your Anthropic account

Configure MCP Server#

bootspring mcp install

This automatically:

  1. Locates Claude Desktop config
  2. Adds Bootspring MCP server
  3. Configures permissions

Manual Configuration#

If automatic setup fails, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

1{ 2 "mcpServers": { 3 "bootspring": { 4 "command": "npx", 5 "args": ["-y", "bootspring", "mcp", "serve"], 6 "env": { 7 "BOOTSPRING_API_KEY": "your-api-key" 8 } 9 } 10 } 11}

Verify MCP Connection#

  1. Open Claude Desktop
  2. Look for "bootspring" in available tools
  3. Test with: "Use bootspring_context to describe this project"

VS Code Integration#

Install Extension#

code --install-extension bootspring.bootspring-vscode

Or install via VS Code:

  1. Open Extensions (Cmd+Shift+X)
  2. Search "Bootspring"
  3. Install

Configure Extension#

Settings (Cmd+,):

{ "bootspring.autoGenerate": true, "bootspring.showStatusBar": true, "bootspring.agentShortcuts": true }

Terminal Integration#

VS Code's integrated terminal works seamlessly:

# From VS Code terminal bootspring generate bootspring agent invoke frontend-expert "Help with this component"

iTerm2 Setup#

Install iTerm2#

brew install --cask iterm2

Configure Profile#

  1. Open iTerm2 Preferences (Cmd+,)
  2. Profiles → Default → General
  3. Set "Send text at start" to: eval "$(bootspring completions zsh)"

Shell Integration#

# Install iTerm2 shell integration curl -L https://iterm2.com/shell_integration/zsh -o ~/.iterm2_shell_integration.zsh echo 'source ~/.iterm2_shell_integration.zsh' >> ~/.zshrc

Warp Terminal#

Warp works out of the box with Bootspring:

# Completions work automatically bootspring [TAB]

Warp Workflows#

Create a Warp workflow for common tasks:

# ~/.warp/workflows/bootspring-start.yaml name: Bootspring Start command: bootspring generate && bootspring status description: Generate context and check status

Raycast Integration#

Install Bootspring Extension#

  1. Open Raycast (Cmd+Space)
  2. Search "Store"
  3. Find "Bootspring"
  4. Install

Quick Commands#

  • bs generate - Generate context
  • bs agents - List agents
  • bs invoke [agent] - Invoke agent

Script Commands#

Create custom Raycast scripts:

1#!/bin/bash 2# ~/.config/raycast/scripts/bootspring-generate.sh 3 4# Required parameters: 5# @raycast.schemaVersion 1 6# @raycast.title Generate Bootspring Context 7# @raycast.mode silent 8 9cd "$PWD" && bootspring generate

Spotlight/Alfred Integration#

Alfred Workflow#

  1. Download Bootspring Alfred Workflow
  2. Import into Alfred
  3. Use bs keyword

Custom Workflow#

# Alfred script filter bootspring agent list --json

Apple Silicon Notes#

Rosetta Compatibility#

Bootspring runs natively on Apple Silicon. No Rosetta needed.

Node.js on M1/M2/M3#

Ensure native ARM build:

1# Check architecture 2node -p "process.arch" 3# Should output: arm64 4 5# If x64, reinstall Node.js 6brew uninstall node 7brew install node

Keychain Integration#

Store API key securely:

1# Add to Keychain 2security add-generic-password -a "$USER" -s "bootspring-api-key" -w "bs_live_xxx" 3 4# Retrieve in scripts 5API_KEY=$(security find-generic-password -a "$USER" -s "bootspring-api-key" -w) 6export BOOTSPRING_API_KEY="$API_KEY"

Add to ~/.zshrc:

export BOOTSPRING_API_KEY=$(security find-generic-password -a "$USER" -s "bootspring-api-key" -w 2>/dev/null)

Troubleshooting#

Command Not Found#

1# Check PATH 2echo $PATH 3 4# Find npm global bin 5npm bin -g 6 7# Add to PATH if missing 8echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc 9source ~/.zshrc

Permission Denied#

1# Fix npm permissions (recommended) 2mkdir -p ~/.npm-global 3npm config set prefix '~/.npm-global' 4echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc 5source ~/.zshrc 6 7# Reinstall 8npm install -g bootspring

SSL Certificate Errors#

# Update CA certificates brew install ca-certificates # Or temporarily disable strict SSL (not recommended) npm config set strict-ssl false

Gatekeeper Blocking#

If macOS blocks execution:

# Allow in Security settings # System Preferences → Security & Privacy → General → Allow # Or via terminal xattr -d com.apple.quarantine $(which bootspring)

Node.js Version Issues#

1# Check version 2node --version 3 4# Upgrade via Homebrew 5brew upgrade node 6 7# Or use nvm 8nvm install 20 9nvm use 20

Health Check#

Run comprehensive diagnostics:

bootspring doctor

Expected output:

Bootspring Health Check ======================= System: ✓ macOS 14.2.1 (Sonoma) ✓ Apple M2 Pro ✓ 16 GB RAM Runtime: ✓ Node.js v20.10.0 (arm64) ✓ npm v10.2.3 ✓ Bootspring v1.2.0 Configuration: ✓ Config file: Valid ✓ Context file: Present ✓ API key: Configured Network: ✓ API: Connected ✓ Latency: 45ms Integrations: ✓ Claude Desktop: Configured ✓ VS Code: Extension installed All 12 checks passed!

Uninstallation#

Remove Bootspring#

npm uninstall -g bootspring

Clean Configuration#

rm -rf ~/.bootspring rm -rf ~/Library/Application\ Support/bootspring

Remove Shell Completions#

Edit ~/.zshrc and remove Bootspring lines.

Remove MCP Configuration#

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and remove the bootspring entry.

Next Steps#