claude-code-glm-suite/SCRIPTS-GUIDE.md

# 📜 Claude Code Scripts Guide

> **Complete guide to all automation scripts for managing Claude Code customizations**

---

## 📑 Table of Contents

1. [Available Scripts](#-available-scripts)
2. [Workflow Examples](#-workflow-examples)
3. [Script Comparison](#-script-comparison)
4. [Quick Reference](#-quick-reference)
5. [Troubleshooting](#-troubleshooting)
6. [Customization](#-customization)

---

## 🔧 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-16
**Version**: 1.0.0