Installation Troubleshooting

January 10, 2026 · View on GitHub

Solutions for common installation and setup issues with BOS-AI.

Pre-Installation Checklist

Before installing BOS-AI, verify you have:

RequirementHow to CheckNotes
Claude Codeclaude --versionMust be installed and working
Gitgit --versionRequired for repository operations
Terminal accessOpen Terminal appmacOS, Linux, or Windows PowerShell
Network accessping github.comRequired to download BOS-AI

Installation Methods

mkdir ~/my-business && cd ~/my-business && git init
curl -fsSL https://raw.githubusercontent.com/TheWayWithin/BOS-AI/main/deployment/scripts/install.sh | bash -s full

Method 2: Manual Installation

If the automatic installer fails:

# Create your business directory
mkdir ~/my-business && cd ~/my-business && git init

# Clone BOS-AI
git clone https://github.com/TheWayWithin/BOS-AI.git temp-bos

# Copy required files
cp -r temp-bos/.claude .
cp temp-bos/CLAUDE.md .

# Clean up
rm -rf temp-bos

# Verify
ls -la .claude/agents/

Common Issues and Solutions

Issue: "curl: command not found"

Symptom: Terminal says curl is not installed.

Solution:

# macOS - install Xcode command line tools
xcode-select --install

# Linux (Ubuntu/Debian)
sudo apt-get install curl

# Linux (CentOS/RHEL)
sudo yum install curl

Issue: "Permission denied"

Symptom: Script fails with permission errors.

Solutions:

  1. Check directory permissions:

    ls -la ~/
# Your home directory should be owned by you

  2. Try a different directory:

    mkdir ~/Documents/my-business && cd ~/Documents/my-business
git init
# Then run installation again

  3. Don't use sudo (unless specifically required):

    # Wrong - don't do this
sudo curl -fsSL ... | bash

# Right - run as normal user
curl -fsSL ... | bash

Issue: "Agents not appearing"

Symptom: After installation, typing @ doesn't show BOS-AI agents.

Solutions:

  1. Restart Claude Code:

    # Exit Claude Code completely
# Open a new terminal
cd ~/my-business
claude code .

  2. Verify installation location:

    ls -la .claude/agents/
# Should show 30+ agent files

  3. Check you're in the right directory:

    pwd
# Should be your business directory
cat CLAUDE.md | head -5
# Should show BOS-AI header

  4. Verify agent file format:

    cat .claude/agents/chassis-intelligence.md | head -10
# Should show agent definition

Issue: "Commands not recognized"

Symptom: /coord or other commands don't work.

Solutions:

  1. Check commands directory:

    ls -la .claude/commands/
# Should show coord.md, meeting.md, etc.

  2. Verify command format:

    cat .claude/commands/coord.md | head -10
# Should show command definition

  3. Use correct syntax:

    # Correct
/coord optimize

# Incorrect
/coord-optimize
@coord optimize
coord optimize

Issue: "Network/download failures"

Symptom: Script fails to download files from GitHub.

Solutions:

  1. Check network connectivity:

    curl -I https://github.com
# Should return HTTP 200

  2. Try alternative download:

    # Download manually in browser, then:
cd ~/Downloads
unzip BOS-AI-main.zip
cd BOS-AI-main
./deployment/scripts/install.sh full ~/my-business

  3. Check for VPN/firewall issues:

    • Temporarily disable VPN
    • Check corporate firewall settings

Issue: "Git not initialized"

Symptom: Error about git repository.

Solution:

cd ~/my-business
git init
# Now run installation again

Issue: ".claude directory already exists"

Symptom: Warning about overwriting existing installation.

Solutions:

  1. Backup and reinstall (recommended for fresh start):

    mv .claude .claude-backup
# Run installation again

  2. Keep existing and update:

    # The installer should offer update option
# Or manually update specific files

Verification Commands

After installation, verify everything works:

# Check agent count (should be 30+)
ls .claude/agents/ | wc -l

# Check commands (should be 5+)
ls .claude/commands/ | wc -l

# Check CLAUDE.md exists
cat CLAUDE.md | head -3

# Check missions directory
ls missions/ | wc -l

# Test in Claude Code
claude code .
# Then type: /coord
# Should show mission menu

Platform-Specific Issues

macOS

Issue: Security warning about unsigned scripts

Solution:

# If macOS blocks the script:
# 1. Open System Preferences → Security & Privacy
# 2. Click "Allow Anyway" for the blocked script
# Or use this command:
xattr -d com.apple.quarantine install.sh
./install.sh full

Windows (WSL)

Issue: Path formatting issues

Solution:

# Use WSL paths, not Windows paths
# Wrong: /mnt/c/Users/Name/my-business
# Right: ~/my-business
cd ~
mkdir my-business
cd my-business
git init
# Run installation

Linux

Issue: Missing dependencies

Solution:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git curl

# CentOS/RHEL
sudo yum install git curl

Getting Help

If none of the above solutions work:

  1. Collect diagnostic information:

    echo "=== System Info ==="
uname -a
echo "=== Git Version ==="
git --version
echo "=== Directory Contents ==="
ls -la
echo "=== .claude Contents ==="
ls -la .claude/ 2>/dev/null || echo "No .claude directory"

  2. Check GitHub Issues:

  3. Use /pmd for analysis:

    /pmd "installation issue: [describe problem]"

Back to README | FAQ