macOS Platform Guide

This tutorial is written primarily for Windows (Git Bash), but most commands work on macOS as-is. This page covers macOS-specific configuration and tools.

Environment Setup

Installation

# 1. Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Node.js
brew install node

# 3. Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 4. Commonly used tools
brew install jq      # JSON processing (needed for the Hooks chapter)
brew install tmux    # Split-pane display for Agent Teams

Shell Configuration

# macOS defaults to zsh
# Put environment variables in ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

# If you're using bash instead
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bash_profile
source ~/.bash_profile

macOS Productivity Tools

Claude Code Monitor (Raycast Extension)

claude-code-monitor is a Raycast extension that provides a Claude Code session monitoring dashboard.

Features:

• Real-time session tracking (status, cost, tokens)
• Menu bar status icon (color-coded)
• Usage analytics panel (cost trends, model distribution)
• Plugin/Skill/MCP management

Installation:

# Requires Raycast
# https://www.raycast.com/

# Install the extension
# Search "Claude Code Monitor" in the Raycast Store
# Or clone from GitHub and install manually

git clone https://github.com/wuyuxiangX/claude-code-monitor.git
cd claude-code-monitor
npm install && npm run build
# Import as a developer extension in Raycast

How it works:

• Captures session lifecycle events via Claude Code hooks
• A Python script writes metadata to ~/.claude/claude-code-monitor/sessions.json
• The extension reads JSON + parses JSONL transcripts for analytics
• Everything is processed locally — no data leaves your machine

Supported editors: VS Code, Cursor, Zed, Windsurf, IntelliJ, WebStorm, PyCharm, GoLand

Supported terminals: Terminal.app, iTerm2, Warp, Ghostty, kitty, tmux

Computer Use (Desktop Automation)

Claude Code Desktop on macOS supports Computer Use — automated mouse and keyboard control.

# No extra setup needed — works out of the box in Claude Code Desktop
# Claude can:
# - Move the mouse and click
# - Switch between apps
# - Work with desktop files
# - Interact with web apps

Note: Computer Use is currently only available in Claude Code Desktop on macOS.

macOS-specific Notes by Chapter

Ch5 Hooks — Notification Sounds

# Play a notification sound on macOS
afplay /System/Library/Sounds/Glass.aiff

# Or use text-to-speech
say "Claude has finished the task"

# Send a system notification
osascript -e 'display notification "Task complete" with title "Claude Code"'

Ch9 Agent Teams — tmux Split Panes

# macOS supports tmux, so Agent Teams can use split-pane mode
brew install tmux

# Claude Code auto-detects tmux availability
# It will create split panes when starting Agent Teams

# iTerm2 also supports native split panes
# Cmd+D for vertical split, Cmd+Shift+D for horizontal split

Ch10 Permissions — Managed Policy Paths

# Managed policy paths on macOS
# /Library/Application Support/ClaudeCode/managed-settings.json
# /Library/Application Support/ClaudeCode/managed-settings.d/*.json
# /Library/Application Support/ClaudeCode/CLAUDE.md

# Requires sudo to write
sudo mkdir -p "/Library/Application Support/ClaudeCode"
sudo cp managed-settings.json "/Library/Application Support/ClaudeCode/"

Ch11 IDE — Desktop App

# Claude Code Desktop on macOS offers extra features:
# - Visual file diff review
# - Live app preview (embedded browser)
# - Parallel multi-session management
# - Scheduled task scheduling
# - Computer Use desktop automation

# Download: https://claude.ai/download

Troubleshooting

Q: Permission issues

# If Claude Code needs access to specific directories,
# macOS may show a permission request dialog.
# Make sure to grant access in System Settings > Privacy & Security.

# Terminal needs "Full Disk Access"
# System Settings > Privacy & Security > Full Disk Access > Terminal.app

Q: Homebrew Node.js conflicts with nvm

# If you have Node.js from both Homebrew and nvm,
# make sure nvm takes priority in your PATH
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# Verify which node is being used
which node
# Should be ~/.nvm/versions/node/... not /opt/homebrew/bin/node

Q: Apple Silicon (M1/M2/M3/M4) Compatibility

# Claude Code is fully compatible with Apple Silicon
# If some npm packages have native dependencies, make sure you're using the ARM build
node -p "process.arch"
# Should output "arm64"

# If you need x86 compatibility
arch -x86_64 npm install