`bash
claude-buddy update [options]
`

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

$3

Removes Claude Buddy from the project.

`bash
claude-buddy uninstall [options]
`

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

$3

Verifies installation integrity and shows status.

`bash
claude-buddy verify
`

Installation Process

$3

`
.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
`

$3

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.

$3

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

$3

`bash


Installation behavior

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

`json
{
"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

$3

`yaml


GitHub Actions example

`dockerfile
FROM node:18-alpine

Install Claude Buddy

WORKDIR /app
`

$3

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

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

Troubleshooting

$3

Installation fails with permission errors:
`bash


Run with appropriate permissions

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

$3

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

$3

`bash


Faster installation (quiet mode)

`bash


All tests

`bash


Check for issues

- 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

$3

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

$3

The installer protects sensitive files:
- .env` files are never modified
- User credentials are preserved
- Git history remains intact

$3

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