Claude Buddy Installation Script

Automated installation and configuration tool for Claude Buddy framework

Overview

The Claude Buddy installation script provides a robust, cross-platform solution for setting up and managing the Claude Buddy AI assistant framework in your development projects. It handles fresh installations, updates, uninstallations, and gracefully degrades when optional dependencies are unavailable.

Features

• Fresh Installation: Sets up all Claude Buddy components with zero configuration
• Smart Updates: Preserves user customizations while updating framework files
• Graceful Degradation: Continues installation when optional dependencies are missing
• Dry-Run Mode: Preview all actions before executing
• Transaction Safety: Automatic rollback on failures
• Cross-Platform: Works on macOS, Linux, and Windows
• Non-Interactive Mode: Perfect for CI/CD pipelines

Quick Start

Installation

# Install globally
npm install -g claude-buddy

# Run installation
claude-buddy install

# Or use npx for one-time installation
npx claude-buddy install

Basic Usage

# Fresh installation in current directory
claude-buddy install

# Install in specific directory
claude-buddy install --target /path/to/project

# Update existing installation
claude-buddy update

# Dry-run mode (preview without changes)
claude-buddy install --dry-run

# Uninstall Claude Buddy
claude-buddy uninstall

# Verify installation
claude-buddy verify

Commands

install

Performs a fresh installation or updates an existing one.

claude-buddy install [options]

Options:

• --target <dir> - Target installation directory (default: current directory)
• --force - Force reinstall even if already installed
• --skip-hooks - Skip hook installation
• --dry-run - Preview changes without executing
• --verbose - Enable detailed logging
• --quiet - Suppress all output except errors
• --non-interactive - Run without user prompts (for CI/CD)

update

Updates an existing installation while preserving customizations.

claude-buddy update [options]

Options:

• --preserve-all - Preserve all files (no updates)
• --merge-config - Merge configuration files instead of replacing

uninstall

Removes Claude Buddy from the project.

claude-buddy uninstall [options]

Options:

• --preserve-customizations - Keep user-created files
• --purge - Complete removal including all customizations

verify

Verifies installation integrity and shows status.

claude-buddy verify

Installation Process

What Gets Installed

.claude/                 # Claude Code integration
├── hooks/               # Python safety hooks (requires UV + Python)
├── hooks.json           # Configuration (replaces buddy-config.json)
├── commands/            # Slash commands
├── agents/              # Specialized agents
└── skills/              # Auto-activating Claude Code Skills (v2.1.0+)
    ├── personas/        # 12 persona skills
    ├── domains/         # 3 domain skills
    └── generators/      # 4 generator skills

directive/               # Project foundation
└── foundation.md        # Foundation document template

specs/                   # Specification storage

🚨 v3.0.0 Breaking Change

The .claude-buddy/ directory has been completely removed in v3.0.0:

• ❌ .claude-buddy/buddy-config.json → ✅ .claude/hooks.json (config section)
• ❌ .claude-buddy/personas/ → ✅ .claude/skills/personas/
• ❌ .claude-buddy/templates/ → ✅ .claude/skills/generators/
• ❌ .claude-buddy/context/ → ✅ .claude/skills/domains/

Migration Required: If upgrading from v2.x, ensure you have:

1. Configuration in .claude/hooks.json (v2.2.0+)
2. Skills directory at .claude/skills/ (v2.1.0+)

See CHANGELOG.md for migration details.

Claude Code Skills

The Skills system provides auto-discovering capabilities that activate based on context:

Persona Skills (12 total):

• scribe - Professional writer and documentation specialist
• architect - Systems design and architecture specialist
• security - Threat modeling and vulnerability analysis
• frontend - UI/UX and accessibility specialist
• backend - API and reliability engineering
• performance - Optimization and bottleneck elimination
• analyzer - Root cause analysis and investigation
• qa - Quality assurance and testing
• refactorer - Code quality and technical debt management
• devops - Infrastructure and deployment
• mentor - Knowledge transfer and education
• po - Product requirements and strategic planning

Domain Skills (3 total):

• react - React.js development patterns and best practices
• jhipster - JHipster full-stack application development
• mulesoft - MuleSoft integration, DataWeave, and Anypoint Platform

Generator Skills (4 total):

• spec-generator - Generate feature specifications from descriptions
• plan-generator - Create implementation plans from specifications
• tasks-generator - Generate task breakdowns from plans
• docs-generator - Create comprehensive technical documentation

Benefits:

• 30-70% token savings compared to manual file loading
• Auto-discovery - skills activate based on keywords, file patterns, and context
• Progressive disclosure - supporting files load only when needed
• Skill composition - multiple skills collaborate naturally

See .claude/skills/README.md for detailed documentation.

Dependencies

Required:

• Node.js >= 18.0.0

Optional:

• UV (Python package manager) - enables safety hooks
• Python 3.8+ - enables safety hooks
• Git - enables version control integration

Graceful Degradation: When optional dependencies are missing, the installer:

• Skips related components with clear warnings
• Installs core functionality successfully
• Provides instructions for enabling skipped features

Configuration

Environment Variables

# Installation behavior
CLAUDE_BUDDY_HOME=/path/to/install       # Override installation directory
CLAUDE_BUDDY_VERBOSE=1                    # Enable verbose logging
CLAUDE_BUDDY_NO_COLOR=1                   # Disable color output
CLAUDE_BUDDY_CONFIG=/path/to/.clauderc   # Custom config file location

Configuration File

Create .claude-buddy-rc.json in your project or home directory:

{
  "installMode": "project",
  "autoUpdate": false,
  "preserveCustomizations": true,
  "hooks": {
    "enabled": true,
    "timeout": 10000
  },
  "logging": {
    "level": "normal",
    "file": ".claude-buddy/install.log"
  }
}

Exit Codes

The installation script uses standard exit codes:

• 0 - Success
• 1 - General error
• 2 - User cancellation
• 10 - Environment validation failed
• 20 - Dependency missing (required)
• 30 - Permission denied
• 40 - Installation corrupted
• 50 - Transaction failed
• 60 - Rollback required

Advanced Usage

CI/CD Integration

# GitHub Actions example
- name: Install Claude Buddy
  run: |
    npx claude-buddy install \
      --non-interactive \
      --target $GITHUB_WORKSPACE \
      --skip-hooks
  env:
    CLAUDE_BUDDY_VERBOSE: 1

Docker Installation

FROM node:18-alpine

# Install Claude Buddy
RUN npx claude-buddy install \
    --non-interactive \
    --target /app

WORKDIR /app

Programmatic Usage

const { execSync } = require('child_process');

// Run installation programmatically
execSync('npx claude-buddy install --non-interactive', {
  cwd: '/path/to/project',
  stdio: 'inherit'
});

Troubleshooting

Common Issues

Installation fails with permission errors:

# Run with appropriate permissions
sudo claude-buddy install

# Or change directory ownership
sudo chown -R $USER:$USER /path/to/project

Hooks not installing:

• Ensure UV is installed: curl -LsSf https://astral.sh/uv/install.sh | sh
• Verify Python 3.8+: python3 --version
• Retry installation: claude-buddy install --force

Update not preserving customizations:

• Use --preserve-all flag: claude-buddy update --preserve-all
• Check .claude-buddy/install-metadata.json for tracked files

Dry-run shows unexpected changes:

• Review current installation: claude-buddy verify
• Check for manual modifications to framework files

For more troubleshooting, see TROUBLESHOOTING.md

Performance

Benchmarks

• Fresh Installation: < 30 seconds
• Update Operation: < 10 seconds
• Dry-Run Analysis: < 5 seconds

Performance Tuning

# Faster installation (quiet mode)
claude-buddy install --quiet

# Skip optional components for speed
claude-buddy install --skip-hooks

Development

Running Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# Performance tests
npm run test:performance

Linting

# Check for issues
npm run lint

# Auto-fix issues
npm run lint:fix

Architecture

Core Modules

• lib/environment.js - Platform and dependency detection
• lib/manifest.js - Component definitions and validation
• lib/installer.js - Fresh installation logic
• lib/updater.js - Update and preservation logic
• lib/uninstaller.js - Removal logic
• lib/transaction.js - Atomic operations with rollback
• lib/logger.js - Logging and user feedback

Transaction System

The installer uses a checkpoint-based transaction system:

1. Pre-install snapshot - Captures current state
2. Planned actions - Defines all operations
3. Execution - Performs actions with validation
4. Checkpoint creation - Saves state at each phase
5. Automatic rollback - Reverts on any failure

Security

File Protection

The installer protects sensitive files:

• .env files are never modified
• User credentials are preserved
• Git history remains intact

Validation

All operations are validated:

• Permission checks before modifications
• Manifest validation before installation
• Integrity verification after completion

Version History

See CHANGELOG.md for detailed version history.

Contributing

For development guidelines and contribution instructions, see the main project CONTRIBUTING.md.

License

MIT License - see LICENSE for details.

Support

• Documentation: Full Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for the Claude Code community