macOS Setup Guide

Complete guide to installing and configuring Bootspring on macOS.

System Requirements#

Installation Methods#

Method 1: Homebrew (Recommended)#

The easiest way to install on macOS:

Method 2: npm Direct#

If you already have Node.js:

Method 3: nvm (Version Management)#

For managing multiple Node.js versions:

Shell Configuration#

Zsh (Default on macOS)#

Add to ~/.zshrc:

Apply changes:

Bash#

Add to ~/.bash_profile:

Apply changes:

Authentication#

Browser Login#

This opens your default browser for authentication.

Device Code (Headless)#

For remote sessions or terminals without browser access:

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

API Key Authentication#

For CI/CD environments:

Add to ~/.zshrc for persistence:

Project Setup#

Initialize New Project#

Interactive Setup#

Walks you through:

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

Quick Setup#

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#

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:

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#

Or install via VS Code:

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

Configure Extension#

Settings (Cmd+,):

Terminal Integration#

VS Code's integrated terminal works seamlessly:

iTerm2 Setup#

Install 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#

Warp Terminal#

Warp works out of the box with Bootspring:

Warp Workflows#

Create a Warp workflow for common tasks:

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:

Spotlight/Alfred Integration#

Alfred Workflow#

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

Custom Workflow#

Apple Silicon Notes#

Rosetta Compatibility#

Bootspring runs natively on Apple Silicon. No Rosetta needed.

Node.js on M1/M2/M3#

Ensure native ARM build:

Keychain Integration#

Store API key securely:

Add to ~/.zshrc:

Troubleshooting#

Command Not Found#

Permission Denied#

SSL Certificate Errors#

Gatekeeper Blocking#

If macOS blocks execution:

Node.js Version Issues#

Health Check#

Run comprehensive diagnostics:

Expected output:

Uninstallation#

Remove Bootspring#

Clean Configuration#

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#

• Generate Context
• VS Code Setup
• Claude Desktop Setup
• Your First Workflow