296 lines
7.0 KiB
Markdown
296 lines
7.0 KiB
Markdown
# Claude Code Customizations - Scripts Guide
|
|
|
|
This guide explains all the automated scripts created for managing Claude Code customizations.
|
|
|
|
## Available Scripts
|
|
|
|
### 1. `install-claude-customizations.sh` 📥
|
|
|
|
**Purpose**: Automated installer for setting up Claude Code customizations on a new machine.
|
|
|
|
**Usage**:
|
|
```bash
|
|
./install-claude-customizations.sh
|
|
```
|
|
|
|
**What it does**:
|
|
- Checks prerequisites (Node.js, npm, python3, curl)
|
|
- Creates directory structure (~/.claude/agents/, plugins/, etc.)
|
|
- Configures settings.json and settings.local.json
|
|
- Installs MCP tools (@z_ai/mcp-server, @z_ai/coding-helper)
|
|
- Sets up plugin configurations
|
|
- Creates agent directory structure (you must copy agent files separately)
|
|
|
|
**Options**:
|
|
- `--skip-agents` - Skip agent file copying (if already present)
|
|
- `--help` - Show help message
|
|
|
|
**Best for**: Fresh installation on a new machine when you have access to agent files from another source.
|
|
|
|
---
|
|
|
|
### 2. `export-claude-customizations.sh` 📦
|
|
|
|
**Purpose**: Export/pack existing customizations for transfer to another machine.
|
|
|
|
**Usage**:
|
|
```bash
|
|
./export-claude-customizations.sh
|
|
```
|
|
|
|
**What it does**:
|
|
- Copies all agent definitions from ~/.claude/agents/
|
|
- Exports plugin configurations
|
|
- Creates settings template (without sensitive API tokens)
|
|
- Exports hooks if present
|
|
- Creates README and MANIFEST
|
|
- Packages everything into a .tar.gz archive
|
|
|
|
**Output**:
|
|
- `claude-customizations-YYYYMMDD_HHMMSS.tar.gz` - Compressed archive
|
|
- `claude-customizations-export/` - Unpacked directory (optional cleanup)
|
|
|
|
**Best for**: Backing up your customizations or transferring to another machine.
|
|
|
|
---
|
|
|
|
### 3. `create-complete-package.sh` 🎁
|
|
|
|
**Purpose**: Creates a complete, distributable package with ALL agent files included.
|
|
|
|
**Usage**:
|
|
```bash
|
|
./create-complete-package.sh
|
|
```
|
|
|
|
**What it does**:
|
|
- Copies ALL agent files from current machine
|
|
- Copies plugin configurations
|
|
- Creates settings templates
|
|
- Copies hooks
|
|
- Generates install.sh script (self-contained installer)
|
|
- Generates verify.sh script
|
|
- Creates comprehensive README
|
|
- Packages everything into .tar.gz archive
|
|
|
|
**Output**:
|
|
- `claude-customizations-complete-YYYYMMDD_HHMMSS.tar.gz` - Complete package
|
|
- `claude-complete-package/` - Unpacked directory with:
|
|
- `agents/` - All agent .md files
|
|
- `plugins/` - Plugin configurations
|
|
- `config/` - Settings templates
|
|
- `install.sh` - Automated installer
|
|
- `verify.sh` - Verification script
|
|
- `README.md` - Package documentation
|
|
- `MANIFEST.json` - Package metadata
|
|
|
|
**Best for**: Creating a complete, ready-to-distribute package that includes everything.
|
|
|
|
---
|
|
|
|
### 4. `verify-claude-setup.sh` ✅
|
|
|
|
**Purpose**: Verify that customizations are properly installed.
|
|
|
|
**Usage**:
|
|
```bash
|
|
./verify-claude-setup.sh
|
|
```
|
|
|
|
**What it checks**:
|
|
- Directory structure (Claude, agents, plugins)
|
|
- Agent categories (8 categories)
|
|
- Configuration files (settings.json, etc.)
|
|
- MCP tools availability (npx, @z_ai packages)
|
|
- Plugin registrations (glm-plan-bug, glm-plan-usage)
|
|
- Critical agent files exist and have content
|
|
- Settings file validity (JSON format, API token configured)
|
|
|
|
**Output**:
|
|
- Pass/Fail status for each check
|
|
- Summary with totals
|
|
- Exit code 0 if all pass, 1 if any fail
|
|
|
|
**Best for**: Troubleshooting installation issues or confirming setup is complete.
|
|
|
|
---
|
|
|
|
## Workflow Examples
|
|
|
|
### Scenario 1: Transfer to New Machine
|
|
|
|
**On source machine**:
|
|
```bash
|
|
# Create complete package
|
|
./create-complete-package.sh
|
|
|
|
# Transfer archive
|
|
scp claude-customizations-complete-*.tar.gz user@new-machine:~/
|
|
```
|
|
|
|
**On new machine**:
|
|
```bash
|
|
# Extract
|
|
tar -xzf claude-customifications-complete-*.tar.gz
|
|
cd claude-complete-package
|
|
|
|
# Install
|
|
./install.sh
|
|
|
|
# Verify
|
|
./verify.sh
|
|
```
|
|
|
|
---
|
|
|
|
### Scenario 2: Fresh Install Without Agent Files
|
|
|
|
```bash
|
|
# Run installer (creates directory structure)
|
|
./install-claude-customizations.sh
|
|
|
|
# Manually copy agent files
|
|
scp -r user@source:~/.claude/agents/* ~/.claude/agents/
|
|
|
|
# Verify
|
|
./verify-claude-setup.sh
|
|
```
|
|
|
|
---
|
|
|
|
### Scenario 3: Backup Customizations
|
|
|
|
```bash
|
|
# Export current setup
|
|
./export-claude-customizations.sh
|
|
|
|
# Store archive safely
|
|
mv claude-customizations-*.tar.gz ~/backups/
|
|
```
|
|
|
|
---
|
|
|
|
### Scenario 4: Create Distribution Package
|
|
|
|
```bash
|
|
# Create complete package for distribution
|
|
./create-complete-package.sh
|
|
|
|
# Upload to share location
|
|
# (GitHub Releases, Google Drive, etc.)
|
|
```
|
|
|
|
---
|
|
|
|
## Script Comparison
|
|
|
|
| Script | Creates Package | Installs | Verifies | Includes Agents |
|
|
|--------|----------------|----------|----------|-----------------|
|
|
| install-claude-customizations.sh | ❌ | ✅ | ❌ | ❌ (copies structure only) |
|
|
| export-claude-customizations.sh | ✅ | ❌ | ❌ | ✅ |
|
|
| create-complete-package.sh | ✅ | ✅ (via install.sh) | ✅ (via verify.sh) | ✅ |
|
|
| verify-claude-setup.sh | ❌ | ❌ | ✅ | N/A |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### To Install Everything:
|
|
```bash
|
|
./create-complete-package.sh # On machine with customizations
|
|
# Transfer to new machine, then:
|
|
./install.sh # Included in package
|
|
./verify.sh # Included in package
|
|
```
|
|
|
|
### To Just Backup:
|
|
```bash
|
|
./export-claude-customizations.sh
|
|
```
|
|
|
|
### To Just Verify:
|
|
```bash
|
|
./verify-claude-setup.sh
|
|
```
|
|
|
|
---
|
|
|
|
## File Locations
|
|
|
|
All scripts are located in: `/home/uroma/`
|
|
|
|
- `install-claude-customizations.sh`
|
|
- `export-claude-customizations.sh`
|
|
- `create-complete-package.sh`
|
|
- `verify-claude-setup.sh`
|
|
|
|
Documentation:
|
|
- `CLAUDE-CUSTOMIZATIONS-README.md` - Complete feature documentation
|
|
- `SCRIPTS-GUIDE.md` - This file
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Script not executable?
|
|
```bash
|
|
chmod +x /path/to/script.sh
|
|
```
|
|
|
|
### Permission denied?
|
|
```bash
|
|
bash /path/to/script.sh
|
|
```
|
|
|
|
### npx not found?
|
|
```bash
|
|
# Install Node.js from https://nodejs.org/
|
|
# Or use nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
|
```
|
|
|
|
### Agent files not copying?
|
|
- Check source directory exists: `ls ~/.claude/agents/`
|
|
- Check permissions: `ls -la ~/.claude/agents/`
|
|
- Verify script has read permissions
|
|
|
|
---
|
|
|
|
## Customization
|
|
|
|
### Modify Agent Categories
|
|
|
|
Edit the `CATEGORIES` array in scripts:
|
|
```bash
|
|
CATEGORIES=("engineering" "marketing" "product" "studio-operations" "project-management" "testing" "design" "bonus")
|
|
```
|
|
|
|
### Add Custom MCP Tools
|
|
|
|
Edit the MCP installation section in install scripts:
|
|
```bash
|
|
npm install -g your-custom-mcp-server
|
|
```
|
|
|
|
### Change Package Format
|
|
|
|
Edit the tar command in export scripts:
|
|
```bash
|
|
# For zip instead:
|
|
zip -r package.zip claude-complete-package/
|
|
```
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
For issues with:
|
|
- **Scripts**: Check script permissions and dependencies
|
|
- **Installation**: Run verify script to identify issues
|
|
- **Agent behavior**: Check agent .md files in ~/.claude/agents/
|
|
- **MCP tools**: Verify npm packages installed with `npm list -g`
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-15
|
|
**Version**: 1.0.0
|