# 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