# 🚀 Claude Code & GLM Suite - Master Integration Prompt

> **Complete installation with ALL sources, explanations, and real-life examples**

---

## ⚠️ BEFORE YOU BEGIN - Read This First!

### **If Using Z.AI / GLM Coding Plan (90% cheaper):**

**You MUST configure GLM FIRST before using Claude Code!**

**🎯 EASIEST METHOD - Use Z.AI Coding Helper Wizard:**

```bash
# Step 1: Install the coding helper
npm install -g @z_ai/coding-helper

# Step 2: Run the interactive GLM setup wizard
npx @z_ai/coding-helper init

# The wizard will:
# - Ask for your Z.AI API key
# - Configure Claude Code for GLM automatically
# - Set up proper model mappings (glm-4.5-air, glm-4.7)
# - Verify everything works

# Step 3: Start Claude Code with GLM configured
claude

# Step 4: Verify GLM is working (enter /status when prompted)
/status
```

**📖 Official GLM Documentation:** https://docs.z.ai/devpack/tool/claude

---

**Alternative: Manual Configuration (if you prefer):**

```bash
# Step 1: Get your API key
# Visit: https://z.ai/
# Sign up for GLM Coding Plan and copy your API key

# Step 2: Install Claude Code (if not installed)
npm install -g @anthropic-ai/claude-code

# Step 3: Create Claude Code settings
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_ZAI_API_KEY_HERE",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7"
  }
}
EOF

# Step 4: Start Claude Code
claude
```

---

### **If Using Anthropic Claude (Official API):**

```bash
# Step 1: Get your API key
# Visit: https://console.anthropic.com/

# Step 2: Create Claude Code settings
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}
EOF

# Step 3: Install Claude Code (if not installed)
npm install -g @anthropic-ai/claude-code

# Step 4: Start Claude Code
claude
```

---

## 📋 HOW TO USE THE MASTER PROMPT

**Once Claude Code is running and configured:**

### **✂️ COPY FROM HERE:**

```text
═══════════════════════════════════════════════════════════════════════════════

I want to install the Ultimate Claude Code & GLM Customization Suite with ALL integrations including agents, MCP tools, code analysis, and automation. Please perform the following complete integration:

## Overview: What We're Installing

This suite includes 7 major components from open-source projects:

1. **contains-studio/agents** - 38 specialized AI agents with PROACTIVELY auto-triggering
2. **@z_ai/mcp-server** - 8 vision and analysis tools (screenshots, videos, diagrams)
3. **@z_ai/coding-helper** - Web search, GitHub integration, GLM setup wizard
4. **llm-tldr** - Token-efficient code analysis (95% reduction, semantic search)
5. **ui-ux-pro-max-skill** - Professional UI/UX design agent with PROACTIVELY auto-triggering
6. **@iannuttall/ralph** - Autonomous agent looping CLI with hooks integration (Advanced - Optional)
7. **claude-codex-settings** - MCP configuration patterns and best practices (reference)

**Agent Architecture Patterns:**
The PROACTIVELY coordinator agents (studio-coach, studio-producer, experiment-tracker, project-shipper) implement proven coordination patterns from autonomous agent frameworks like Ralph, using supervisor-agent delegation and shared context management.

Each component is explained below with real-life examples showing the benefits.

---

## Step 1: Install Contains Studio Agents (38 agents with PROACTIVELY auto-triggering)

Source: https://github.com/contains-studio/agents

Clone the contains-studio/agents repository:
git clone https://github.com/contains-studio/agents.git /tmp/contains-studio-agents

Copy all agents to Claude Code agents directory:
cp -r /tmp/contains-studio-agents/agents/* ~/.claude/agents/

### What This Provides:

37 specialized agents across 8 departments:
- **Engineering (7):** AI Engineer, Backend Architect, DevOps Automator, Frontend Developer, Mobile Builder, Rapid Prototyper, Test Writer/Fixer
- **Marketing (7):** TikTok Strategist, Growth Hacker, Content Creator, Instagram Curator, Reddit Builder, Twitter Engager, App Store Optimizer
- **Design (6):** Brand Guardian, UI Designer, UX Researcher, Visual Storyteller, Whimsy Injector, **UI/UX Pro Max**
- **Product (3):** Feedback Synthesizer, Sprint Prioritizer, Trend Researcher
- **Project Management (3):** Experiment Tracker, Project Shipper, Studio Producer
- **Studio Operations (5):** Analytics Reporter, Finance Tracker, Infrastructure Maintainer, Legal Compliance Checker, Support Responder
- **Testing (5):** API Tester, Performance Benchmarker, Test Results Analyzer, Tool Evaluator, Workflow Optimizer
- **Bonus (3):** Studio Coach, Agent Updater, Joker

### 🎯 Auto-Triggering System: How Agents Coordinate

**Architecture Overview:**

The 38 agents are divided into two types:
- **7 PROACTIVELY Coordinators** - Auto-trigger based on context and coordinate specialists
- **1 Utility Agent** - Manually triggered for maintenance (agent-updater)
- **30 Specialist Agents** - Execute specific domain tasks when called

**How It Works:**

There are **two pathways** to use agents:

1. **Automatic** - Coordinators auto-trigger and call specialists as needed
2. **Direct** - You manually invoke any specialist for precise control

This gives you automation when you want it, control when you need it.

---

**7 PROACTIVELY Agents** (meta-coordinators that auto-trigger based on context):

**Plus 1 Utility Agent** (manually triggered for maintenance):

#### Design Department (2)

1. **ui-ux-pro-max** - Triggers on UI/UX design work
   - Professional design patterns and accessibility
   - 50+ styles, 97 color palettes, WCAG compliance
   - Example: "Create a pricing page" → ui-ux-pro-max applies professional design patterns

2. **whimsy-injector** - Triggers after UI/UX changes
   - Adds delightful micro-interactions
   - Makes interfaces memorable
   - Example: You create a loading spinner → whimsy-injector adds bounce animation and encouraging messages

#### Engineering Department (1)

3. **test-writer-fixer** - Triggers after code modifications
   - Automatically writes comprehensive tests
   - Fixes broken tests
   - Example: You modify authentication code → test-writer-fixer writes unit tests automatically

#### Project Management Department (3)

4. **experiment-tracker** - Triggers when experiments are started or modified
   - Tracks A/B tests and feature experiments
   - Defines metrics and monitors results
   - Example: You add a feature flag → experiment-tracker sets up tracking and success metrics

5. **studio-producer** - Triggers when coordinating across multiple teams
   - Cross-team coordination and resource allocation
   - Workflow optimization and dependency management
   - Example: "Design and engineering need to collaborate" → studio-producer schedules and coordinates

6. **project-shipper** - Triggers when approaching launch milestones
   - Launch coordination and release management
   - Go-to-market strategy and stakeholder communication
   - Example: "We're releasing next week" → project-shipper plans launch activities

#### Bonus Department (1)

7. **studio-coach** - Triggers on complex multi-agent tasks
   - Coordinates multiple specialists
   - Motivates and aligns agents when stuck
   - Example: "Build a viral TikTok app in 2 weeks" → studio-coach organizes frontend, backend, marketing agents

#### Utility Agent (On-Demand)

8. **agent-updater** - Manually triggered for agent synchronization
   - Checks GitHub for agent updates
   - Downloads and installs new/updated agents safely
   - Preserves local customizations
   - Example: "Check for agent updates" → agent-updater fetches latest from GitHub and syncs your installation

---

**🔄 Real Workflow Example:**

You: "I need a viral TikTok app in 2 weeks"
      ↓
[studio-coach PROACTIVELY triggers]
      ↓
studio-coach analyzes and coordinates:
  → rapid-prototyper (specialist) builds MVP
  → tiktok-strategist (specialist) plans viral features
  → frontend-developer (specialist) builds UI
      ↓
[whimsy-injector PROACTIVELY triggers]
      ↓
whimsy-injector adds delightful touches
      ↓
[project-shipper PROACTIVELY triggers]
      ↓
project-shipper plans launch strategy
      ↓
Result: Complete app, launch-ready ✓

**Key Point:** You don't need to manually orchestrate! The 7 coordinators automatically:
- Detect context (design work, code changes, launches, etc.)
- Call appropriate specialist agents
- Coordinate multi-agent workflows
- Ensure quality and completeness

You can ALSO directly call any specialist agent anytime for manual control.

---
## Step 1.5: Install UI/UX Pro Max Skill (Slash Commands)

The repository includes the **ui-ux-pro-max skill** which provides design guidance and recommendations.

Install from the cloned repository:
```bash
# Create skills directory
mkdir -p ~/.claude/skills

# Copy ui-ux-pro-max skill (includes search.py for design patterns)
cp -r claude-code-glm-suite/skills/ui-ux-pro-max ~/.claude/skills/

# Make Python scripts executable
chmod +x ~/.claude/skills/ui-ux-pro-max/scripts/*.py
```

### What This Provides:

**ui-ux-pro-max skill** - A slash command you can invoke anytime:
- Usage: Type `/ui-ux-pro-max` or use it in your prompts
- Search 50+ design patterns by keyword, domain, and stack
- Get recommendations for landing pages, dashboards, pricing tables, etc.
- Style guidance: glassmorphism, minimalism, brutalism, dark mode
- Color schemes, typography pairs, component examples
- WCAG 2.1 accessibility compliance

Example: "Use ui-ux-pro-max to design a professional CTA section"


## Step 1.75: Install Agent Sync Script (Keep Agents Updated)

Source: https://github.rommark.dev/admin/claude-code-glm-suite

Install the automated sync script to keep your agents up-to-date:

# Download sync-agents.sh
wget -O ~/.claude/sync-agents.sh https://raw.githubusercontent.com/github.rommark.dev/admin/claude-code-glm-suite/main/sync-agents.sh

# Make it executable
chmod +x ~/.claude/sync-agents.sh

### What This Provides:

**Automated agent synchronization:**
- Fetches latest agents from official GitHub repository
- Creates timestamped backups before updating
- Detects new, updated, and customized agents
- Safely updates while preserving your customizations
- Commits changes to git (if configured)
- Pushes updates to your Gitea repository

**Usage:**

# Run sync manually
~/.claude/sync-agents.sh

# Or set Gitea repository URL to auto-push
export GITEA_REPO_URL="https://github.rommark.dev/admin/claude-code-glm-suite.git"
~/.claude/sync-agents.sh

# Also update repository agents (for installers)
export REPO_AGENTS_DIR="/path/to/claude-code-glm-suite/agents"
~/.claude/sync-agents.sh

**How it works:**
1. Clones latest agents from `https://github.com/contains-studio/agents`
2. Compares with your local `~/.claude/agents/`
3. Identifies:
   - ✨ New agents to add
   - 📝 Updated agents to refresh
   - ⚠️ Custom agents to preserve
4. Creates backup: `~/.claude/agents.backup.YYYYMMDD-HHMMSS/`
5. Applies updates safely
6. Reports all changes
7. [Optional] Commits to git and pushes to Gitea

**Key Features:**
- **Safe Updates**: Always creates backups before modifying
- **Smart Detection**: Preserves agents you've customized
- **Dual Sync**: Updates both local agents AND repository agents
- **Git Integration**: Commits and pushes automatically
- **Detailed Logging**: Tracks all changes in `~/.claude/agents/update.log`

**Keeping Agents Updated:**
Run the sync script regularly (weekly or monthly) to get the latest agent improvements:

# Add to crontab for automatic weekly sync
0 2 * * 0 ~/.claude/sync-agents.sh

Or manually check for updates anytime:

~/.claude/sync-agents.sh

**Rollback if needed:**

# List backups
ls -la ~/.claude/agents.backup.*

# Restore a backup
rm -rf ~/.claude/agents
mv ~/.claude/agents.backup.YYYYMMDD-HHMMSS ~/.claude/agents

---

## Step 2: Install MCP Vision & Analysis Tools

Source: https://github.com/zai-ai/mcp-server

Install Z.AI MCP server for vision tools:
npm install -g @z_ai/mcp-server

Verify installation:
npx @z_ai/mcp-server --help

### What This Provides (8 MCP Tools):

1. **analyze_image** - Understand any image (screenshots, photos, designs)
2. **analyze_video** - Analyze video content for key moments
3. **ui_to_artifact** - Convert UI screenshots to code
4. **extract_text** - OCR text extraction from images
5. **diagnose_error** - Understand errors from screenshots
6. **ui_diff_check** - Compare two UI screenshots
7. **analyze_data_viz** - Extract insights from dashboards/charts
8. **understand_diagram** - Understand technical diagrams (UML, flowcharts)

**Key Features:**
- Screenshot-to-code conversion
- Error diagnosis from images
- Video and diagram understanding
- UI comparison and analysis

---

## Step 3: Install MCP Web & GitHub Tools

Source: https://github.com/fcakyon/claude-codex-settings (inspired by)

Install Z.AI coding helper:
npm install -g @z_ai/coding-helper

Verify installation:
npx @z_ai/coding-helper --help

### What This Provides (3 MCP Tools):

1. **web-search-prime** - AI-optimized web search for current information
2. **web-reader** - Convert any web page to clean markdown
3. **zread** - Read and analyze entire GitHub repositories

**Key Features:**
- Real-time web search for current information
- Repository analysis without manual file pasting
- Web page to clean markdown conversion

---

## Step 4: Install llm-tldr (Token-Efficient Code Analysis)

Source: https://github.com/parcadei/llm-tldr

Install llm-tldr:
pip install llm-tldr

Initialize for current directory:
tldr warm .

### What This Provides:

**95% token reduction** while preserving code understanding via 5-layer analysis:
- **Layer 1 (AST)** - Functions, classes, imports structure
- **Layer 2 (Call Graph)** - Who calls what (forward/backward)
- **Layer 3 (CFG)** - Control flow, complexity metrics
- **Layer 4 (DFG)** - Data flow, variable transformations
- **Layer 5 (PDG)** - Program dependence, slicing for debugging

**18 MCP Tools including:**
- `context` - LLM-ready summaries (95% token savings)
- `semantic` - Search by behavior, not just text
- `slice` - Show only code affecting a specific line
- `impact` - Who calls this function? (refactoring safety)
- `cfg` - Control flow graph
- `dfg` - Data flow graph
- And 12 more...

**Key Features:**
- 95% token reduction for large codebases
- Semantic search by behavior (not just text)
- Program slicing for precise debugging
- Impact analysis for safe refactoring

---

## Step 5: Configure MCP Servers in Claude Code

Create MCP configuration for TLDR:
mkdir -p ~/.claude
cat > ~/.claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    },
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    }
  }
}
EOF

Note: TLDR MCP server provides 18 tools for code analysis.
Vision tools from @z_ai/mcp-server are automatically available.

---

## Step 6: Configure Ralph CLI Autonomous Looping (Advanced - Optional)

Source: https://github.com/iannuttall/ralph

**What Ralph Provides:**
Ralph is an autonomous agent orchestration tool that creates infinite loops until task completion. Unlike single-pass PROACTIVELY agents, Ralph maintains state across multiple iterations and coordinates agents through complex workflows.

**Key Differences:**
- **PROACTIVELY Agents**: Single-pass coordination, one interaction
- **Ralph CLI**: Infinite looping, stateful, autonomous until done

### Installation:

Install Ralph CLI:
npm install -g @iannuttall/ralph

Verify installation:
ralph --version

### Create Ralph Auto-Trigger Hook:

mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/ralph-auto-trigger.sh << 'EOF'
#!/bin/bash
# Ralph Auto-Trigger Hook - Enhanced with Background Task Spawning
# Automatically starts Ralph CLI in background when needed
#
# Modes (via RALPH_AUTO_MODE environment variable):
#   "always"    - Start Ralph for every request
#   "agents"    - Only for agent requests (default)
#   "off"       - Disable auto-trigger
#
# Background Execution:
#   - Ralph runs as background process (non-blocking)
#   - Claude Code continues immediately
#   - Ralph output logged to: ~/.claude/ralph-output.log
#   - Ralph PID tracked in: ~/.claude/ralph.pid

set -euo pipefail

# Configuration
CLAUDE_DIR="$HOME/.claude"
RALPH_STATE_FILE="$CLAUDE_DIR/ralph-loop.local.md"
RALPH_PID_FILE="$CLAUDE_DIR/ralph.pid"
RALPH_LOG_FILE="$CLAUDE_DIR/ralph-output.log"
RALPH_LOCK_FILE="$CLAUDE_DIR/ralph.lock"

# Read hook input from stdin
HOOK_INPUT=$(cat)
USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")

# Fallback: if no JSON input, use first argument
if [[ -z "$USER_PROMPT" && $# -gt 0 ]]; then
    USER_PROMPT="$1"
fi

# Get Ralph mode (default: agents)
RALPH_AUTO_MODE="${RALPH_AUTO_MODE:-agents}"
RALPH_MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"

# Exit if auto-trigger is disabled
if [[ "$RALPH_AUTO_MODE" == "off" ]]; then
    exit 0
fi

# Check if Ralph is already running (via lock file)
if [[ -f "$RALPH_LOCK_FILE" ]]; then
    # Check if process is still alive
    LOCK_PID=$(cat "$RALPH_LOCK_FILE" 2>/dev/null || echo "")
    if [[ -n "$LOCK_PID" ]] && kill -0 "$LOCK_PID" 2>/dev/null; then
        # Ralph is already running, don't start another instance
        exit 0
    else
        # Lock file exists but process is dead, clean up
        rm -f "$RALPH_LOCK_FILE" "$RALPH_PID_FILE"
    fi
fi

# Agent detection list (lowercase for matching)
AGENTS=(
    "ai-engineer" "backend-architect" "devops-automator" "frontend-developer"
    "mobile-app-builder" "rapid-prototyper" "test-writer-fixer"
    "tiktok-strategist" "growth-hacker" "content-creator" "instagram-curator"
    "reddit-builder" "twitter-engager" "app-store-optimizer"
    "brand-guardian" "ui-designer" "ux-researcher" "visual-storyteller"
    "whimsy-injector" "ui-ux-pro-max"
    "feedback-synthesizer" "sprint-prioritizer" "trend-researcher"
    "experiment-tracker" "project-shipper" "studio-producer" "studio-coach"
    "analytics-reporter" "finance-tracker" "infrastructure-maintainer"
    "legal-compliance-checker" "support-responder"
    "api-tester" "performance-benchmarker" "test-results-analyzer"
    "tool-evaluator" "workflow-optimizer"
    "joker" "agent-updater"
    "explore" "plan" "general-purpose"
)

# Detect agent request (case-insensitive)
agent_detected=false
detected_agent=""

for agent in "${AGENTS[@]}"; do
    if echo "$USER_PROMPT" | grep -iq "$agent"; then
        agent_detected=true
        detected_agent="$agent"
        break
    fi
done

# Determine if we should start Ralph
should_trigger=false

case "$RALPH_AUTO_MODE" in
    "always")
        # Trigger on all prompts
        should_trigger=true
        ;;
    "agents")
        # Only trigger on agent requests OR development keywords
        if [[ "$agent_detected" == true ]]; then
            should_trigger=true
        elif echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize|write|generate|delegate|autonomous"; then
            should_trigger=true
            detected_agent="general-development"
        fi
        ;;
esac

if [[ "$should_trigger" == true ]]; then
    # Create Ralph state file
    mkdir -p "$CLAUDE_DIR"

    cat > "$RALPH_STATE_FILE" << EOF
# Ralph Loop State - Auto-Triggered
# Generated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

**User Request:**
$USER_PROMPT

**Detected Agent:** $detected_agent
**Mode:** $RALPH_AUTO_MODE
**Max Iterations:** $RALPH_MAX_ITERATIONS
**Timestamp:** $(date -Iseconds)

## Context

This state file was automatically generated by the Ralph auto-trigger hook.
Ralph CLI will read this file and autonomously execute the request.

## Auto-Trigger Details

- Triggered by: Claude Code UserPromptSubmit hook
- Trigger mode: $RALPH_AUTO_MODE
- Background execution: Yes (non-blocking)
- Log file: $RALPH_LOG_FILE

## Usage

Ralph is running autonomously in the background. Monitor progress:

bash
# View Ralph output in real-time
tail -f ~/.claude/ralph-output.log

# Check if Ralph is still running
ps aux | grep ralph

# Stop Ralph manually
kill $(cat ~/.claude/ralph.pid)
rm ~/.claude/ralph.lock


EOF

    # Spawn Ralph in background (NON-BLOCKING)
    if command -v ralph &> /dev/null; then
        # Create log file
        touch "$RALPH_LOG_FILE"

        # Start Ralph in background with nohup (survives terminal close)
        echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Starting Ralph in background..." >> "$RALPH_LOG_FILE"
        echo "Mode: $RALPH_AUTO_MODE" >> "$RALPH_LOG_FILE"
        echo "Agent: $detected_agent" >> "$RALPH_LOG_FILE"
        echo "Max iterations: $RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE"
        echo "---" >> "$RALPH_LOG_FILE"

        # Start Ralph in background
        nohup ralph build "$RALPH_MAX_ITERATIONS" >> "$RALPH_LOG_FILE" 2>&1 &
        RALPH_PID=$!

        # Save PID for tracking
        echo "$RALPH_PID" > "$RALPH_PID_FILE"
        echo "$RALPH_PID" > "$RALPH_LOCK_FILE"

        # Log the trigger
        {
            echo "[$(date -u +"%Y-%m-%d %H:%M:%S UTC")] Ralph auto-triggered"
            echo "  Mode: $RALPH_AUTO_MODE"
            echo "  Agent: $detected_agent"
            echo "  PID: $RALPH_PID"
            echo "  Log: $RALPH_LOG_FILE"
        } >> "$CLAUDE_DIR/ralph-trigger.log" 2>/dev/null || true

        # Notify user via stderr (visible in Claude Code)
        echo "🔄 Ralph CLI auto-started in background" >&2
        echo "   PID: $RALPH_PID" >&2
        echo "   Agent: $detected_agent" >&2
        echo "   Monitor: tail -f ~/.claude/ralph-output.log" >&2
        echo "   Stop: kill \$(cat ~/.claude/ralph.pid)" >&2
    else
        # Ralph not installed, just create state file
        echo "⚠️  Ralph CLI not installed. State file created for manual use." >&2
        echo "   Install: npm install -g @iannuttall/ralph" >&2
    fi
fi

# Exit immediately (NON-BLOCKING - Claude Code continues)
exit 0
EOF

chmod +x ~/.claude/hooks/ralph-auto-trigger.sh

### Configure Hooks:

Create hooks.json to enable Ralph auto-trigger:
cat > ~/.claude/hooks.json << 'EOF'
{
  "description": "User hooks for Ralph auto-trigger",
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/home/uroma/.claude/hooks/ralph-auto-trigger.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

Note: Replace "/home/uroma" with your actual home directory if different.

### What This Provides:

**Background Autonomous Looping:**
- Ralph runs as background process (NON-BLOCKING)
- Claude Code continues immediately
- Ralph output logged to: ~/.claude/ralph-output.log
- Ralph PID tracked in: ~/.claude/ralph.pid
- State preserved in `.claude/ralph-loop.local.md`
- Can handle complex multi-step workflows

**Control Modes:**

# Mode 1: Auto-loop only for agent requests (default)
export RALPH_AUTO_MODE="agents"

# Mode 2: Auto-loop for everything
export RALPH_AUTO_MODE="always"

# Mode 3: Disable auto-loop
export RALPH_AUTO_MODE="off"

# Set max iterations (default: 50)
export RALPH_MAX_ITERATIONS="100"

### How It Works (Background Execution):

1. You request in Claude Code: "Build a TikTok app in 2 weeks"
2. Hook detects agent language
3. Hook spawns Ralph in BACKGROUND (non-blocking)
4. Claude Code immediately continues (you can keep working!)
5. Ralph autonomously iterates in background:
   - Iteration 1: rapid-prototyper builds MVP
   - Iteration 2: tiktok-strategist plans viral features
   - Iteration 3: frontend-developer builds UI
   - Continues until Ralph completes max iterations
6. Monitor Ralph: tail -f ~/.claude/ralph-output.log
7. Stop Ralph anytime: kill $(cat ~/.claude/ralph.pid)

### Monitoring Ralph:

# View Ralph output in real-time
tail -f ~/.claude/ralph-output.log

# Check if Ralph is still running
ps aux | grep ralph
# Or check the PID file
cat ~/.claude/ralph.pid

# View Ralph trigger log
cat ~/.claude/ralph-trigger.log

### Canceling Ralph:

If Ralph is running in background and you want to stop:

# Method 1: Kill by PID (recommended)
kill $(cat ~/.claude/ralph.pid)
rm ~/.claude/ralph.lock

# Method 2: Kill by process name
pkill -f "ralph build"

# Method 3: Disable auto-mode (prevents future triggers)
export RALPH_AUTO_MODE="off"

# Method 4: Delete state file (Ralph will stop on next iteration)
rm ~/.claude/ralph-loop.local.md

### Ralph vs PROACTIVELY Agents:

| Feature | Ralph CLI (Background) | PROACTIVELY Agents |
|---------|------------------------|-------------------|
| **Execution** | Multi-loop, background process | Single interaction |
| **Blocking** | NON-BLOCKING (runs in bg) | Blocking (waits for response) |
| **State** | Persisted in file + log | Context only |
| **Control** | Manual stop via PID | Automatic completion |
| **Complexity** | Handles complex workflows | Quick coordination |
| **Setup** | Requires hook + script | Built-in to agents |
| **Best For** | Large projects, overnight coding | Quick tasks, human collaboration |

**You can use BOTH together:**
- Use Ralph for complex, multi-step projects (autonomous)
- Use PROACTIVELY agents for quick tasks (interactive)
- Set RALPH_AUTO_MODE="agents" for hybrid approach
- Ralph runs in background while you continue working in Claude Code

---

## Step 7: Verify Complete Installation

Run comprehensive checks:

# 1. Verify agents (should be 38+ files)
ls -la ~/.claude/agents/
find ~/.claude/agents -name "*.md" | wc -l

# 2. Verify MCP tools
npx @z_ai/mcp-server --help
npx @z_ai/coding-helper --help
tldr --help

# 3. Verify TLDR indexing
tldr status .

# 4. Verify Ralph CLI (if installed)
ralph --version

# 5. Verify Ralph hook
ls -la ~/.claude/hooks/ralph-auto-trigger.sh

# 6. Test Claude Code
claude --version

Expected results:
- ✅ 39+ agent files (38 agents + README)
- ✅ All 8 departments present
- ✅ MCP tools accessible
- ✅ TLDR indexed current directory
- ✅ Settings configured
- ⚠️ Ralph CLI (optional - verify if installed in Step 6)

---

## Summary: What You Now Have

### 40+ AI Agents
Organized across 8 departments with PROACTIVELY auto-triggering

### 15+ MCP Tools
- 8 vision/analysis tools (@z_ai/mcp-server)
- 3 web/GitHub tools (@z_ai/coding-helper)
- 18 code analysis tools (llm-tldr)

### Three Auto-Triggering Systems
- **PROACTIVELY keyword** (context-aware, built into agents)
- **Ralph CLI** (autonomous looping, optional advanced setup)
- **Hooks-based** (event-driven, for Ralph integration)

### Complete Integration Benefits

**Token Efficiency:**
- TLDR reduces code context by 95%
- $100/month savings on API costs for large codebases

**Code Understanding:**
- 5-layer analysis (AST → PDG)
- Semantic search by behavior
- Impact analysis for safe refactoring

**Visual Capabilities:**
- Screenshot-to-code conversion
- Error diagnosis from images
- Video and diagram understanding

**Automation:**
- Auto-test writing after code changes
- Auto-UI enhancement after design changes
- Auto-coordination for complex tasks

**Up-to-Date Information:**
- Real-time web search
- Repository analysis
- Current documentation

Please execute this complete integration step by step and confirm when each component is installed.

═══════════════════════════════════════════════════════════════════════════════
```

**✂️ COPY ENDS HERE**

---

---

# ═══════════════════════════════════════════════════════════════════════════════
# 📖 REAL-LIFE EXAMPLES: HOW AUTO-TRIGGERING WORKS
# ═══════════════════════════════════════════════════════════════════════════════

> ⚠️ **IMPORTANT: These are ILLUSTRATIVE EXAMPLES ONLY**
>
> The examples below demonstrate the conceptual difference between working **without** auto-triggering agents versus **with** auto-triggering agents.
> These are simplified scenarios to help you understand how the PROACTIVELY system improves your workflow.
>
> **These are not actual output promises** - actual results will vary based on your specific use case, context, and model capabilities.

## Example 1: Adding OAuth Authentication

### ❌ WITHOUT Auto-Triggering Agents

You: Help me add OAuth to my app
Claude: [Writes code, but no tests]
You: [Manually write tests later]
Claude: [Fixes bugs]

### ✅ WITH Auto-Triggering Agents

You: Help me add OAuth to my app
Claude: [Writes code]
[test-writer-fixer PROACTIVELY triggers]
test-writer-fixer: I've automatically created comprehensive tests for your OAuth implementation
Result: Code + tests complete in one interaction ✓

---

## Example 2: Creating a Loading Spinner

### ❌ WITHOUT Auto-Triggering Agents

You: Create a loading spinner
Claude: [Creates basic spinner]
You: [Manually request improvements later]
Claude: [Adds animation]

### ✅ WITH Auto-Triggering Agents

You: Create a loading spinner
Claude: [Creates spinner]
[whimsy-injector PROACTIVELY triggers]
whimsy-injector: I've enhanced your spinner with bounce animation and encouraging messages
Result: Delightful spinner created automatically ✓

---

## Example 3: Launching a New Feature

### ❌ WITHOUT Auto-Triggering Agents

You: We're launching next week
Claude: [Doesn't know what to prepare]
You: [Manually create launch checklist]
Claude: [Helps with specific items]

### ✅ WITH Auto-Triggering Agents

You: We're launching next week
[project-shipper PROACTIVELY triggers]
project-shipper: I've created a complete launch plan with:
- Pre-launch readiness checklist
- Go-to-market strategy
- Stakeholder communication plan
- Success metrics and monitoring
Result: Launch-ready plan created automatically ✓

---

## Example 4: Adding a Feature Flag

### ❌ WITHOUT Auto-Triggering Agents

You: Add feature flag for new checkout
Claude: [Adds flag, but no tracking]
You: [Manually set up analytics later]

### ✅ WITH Auto-Triggering Agents

You: Add feature flag for new checkout
Claude: [Adds flag]
[experiment-tracker PROACTIVELY triggers]
experiment-tracker: I've configured tracking for this experiment:
- Success metrics defined
- Analytics events set up
- Rollout plan created
- Sample size calculated
Result: A/B test ready to run ✓

---

## Example 5: Complex Multi-Agent Task

### ❌ WITHOUT Auto-Triggering Agents

You: Build viral TikTok app in 2 weeks
Claude: [Overwhelmed, doesn't know where to start]
You: [Manually coordinate frontend, backend, marketing teams]

### ✅ WITH Auto-Triggering Agents

You: Build viral TikTok app in 2 weeks
[studio-coach PROACTIVELY triggers]
studio-coach: I'll coordinate this complex project:
→ Calling rapid-prototyper for MVP
→ Calling tiktok-strategist for viral features
→ Calling frontend-developer for UI
→ Calling project-hipper for launch planning
[All agents work together seamlessly]
Result: Complete app, launch-ready, on time ✓

---

## Key Differences Summary

| Aspect | Without Auto-Trigger | With Auto-Trigger |
|--------|---------------------|-------------------|
| **Test Coverage** | Manual, forgettable | Automatic, comprehensive |
| **UI Polish** | Basic, functional | Delightful, memorable |
| **Launch Prep** | Last-minute, chaotic | Planned, organized |
| **Experiment Tracking** | Missing, incomplete | Defined, measurable |
| **Complex Projects** | Overwhelming, fragmented | Coordinated, smooth |
| **Follow-up Required** | Always needed | Built-in |

---

## Why This Matters

**Time Savings:**
- Without: Multiple back-and-forth interactions
- With: Complete in one interaction

**Quality:**
- Without: Inconsistent, forgets steps
- With: Comprehensive, best practices applied

**Peace of Mind:**
- Without: Did I remember everything?
- With: Agents handle it automatically

**Scalability:**
- Without: Manual coordination doesn't scale
- With: Automated coordination handles complexity

---

## ⚡ PROACTIVELY vs Hooks-Based

### PROACTIVELY System (Context-Aware)

**How it works:**
- Claude analyzes the context of your request
- Automatically determines which coordinator to trigger
- Coordinator calls specialist agents as needed

**Examples:**
- You write code → test-writer-fixer triggers
- You design UI → whimsy-injector triggers
- You mention launch → project-shipper triggers

**Benefits:**
- No configuration needed
- Works based on natural language context
- Can be overridden by manual requests

### Hooks-Based System (Event-Driven)

**How it works:**
- Configured in `~/.claude/hooks.json`
- Triggers on specific events (prompt submit, tool output, etc.)

**Example Configuration:**
```json
{
  "userPromptSubmitHook": "test-writer-fixer@agent",
  "toolOutputHook": "whimsy-injector@agent"
}
```

**Benefits:**
- Predictable triggers
- Fine-grained control
- Works alongside PROACTIVELY system

### Combined Power

You can use BOTH systems together:
- PROACTIVELY: Automatic context-aware triggers
- Hooks: Additional event-driven triggers
- Result: Comprehensive automation coverage

---

# 📚 AGENT DEPARTMENTS AND SPECIALTIES

## Engineering Department (7 agents)

1. **ai-engineer** - ML/LLM feature integration
2. **backend-architect** - API design, database optimization
3. **devops-automator** - CI/CD, cloud infrastructure
4. **frontend-developer** - React/Vue/Angular UI development
5. **mobile-app-builder** - iOS/Android native apps
6. **rapid-prototyper** - Quick MVPs and prototypes
7. **test-writer-fixer** - Auto test writing (PROACTIVELY)

## Marketing Department (7 agents)

1. **tiktok-strategist** - Viral TikTok marketing
2. **growth-hacker** - Viral growth loops
3. **content-creator** - Multi-platform content
4. **instagram-curator** - Visual content strategy
5. **reddit-community-builder** - Reddit engagement
6. **twitter-engager** - Twitter growth
7. **app-store-optimizer** - ASO and rankings

## Design Department (6 agents)

1. **brand-guardian** - Brand consistency
2. **ui-designer** - Interface design
3. **ux-researcher** - User research
4. **visual-storyteller** - Visual narratives
5. **whimsy-injector** - Delight injection (PROACTIVELY)
6. **ui-ux-pro-max** - Professional UI/UX (PROACTIVELY)

## Product Department (3 agents)

1. **feedback-synthesizer** - User feedback analysis
2. **sprint-prioritizer** - Feature prioritization
3. **trend-researcher** - Market trend identification

## Project Management Department (3 agents)

1. **experiment-tracker** - A/B test tracking (PROACTIVELY)
2. **project-shipper** - Launch coordination (PROACTIVELY)
3. **studio-producer** - Team coordination (PROACTIVELY)

## Studio Operations Department (5 agents)

1. **analytics-reporter** - Data insights
2. **finance-tracker** - Financial management
3. **infrastructure-maintainer** - System maintenance
4. **legal-compliance-checker** - Legal compliance
5. **support-responder** - Customer support

## Testing Department (5 agents)

1. **api-tester** - API testing
2. **performance-benchmarker** - Performance optimization
3. **test-results-analyzer** - Test analysis
4. **tool-evaluator** - Tool assessment
5. **workflow-optimizer** - Process improvement

## Bonus Department (3 agents)

1. **studio-coach** - Agent coordination (PROACTIVELY)
2. **agent-updater** - Agent updates (on-demand)
3. **joker** - Humor injection

---

# 🔧 CONFIGURATION FILES

## ~/.claude/settings.json

Main Claude Code configuration file:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "3000000"
  }
}
```

### For Z.AI / GLM:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-zai-key",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7"
  }
}
```

## ~/.claude/claude_desktop_config.json

MCP server configuration:

```json
{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    },
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    },
    "zai-web": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"]
    }
  }
}
```

## ~/.claude/hooks.json

Auto-triggering hooks:

```json
{
  "userPromptSubmitHook": "test-writer-fixer@agent",
  "toolOutputHook": "whimsy-injector@agent"
}
```

---

# 🎯 QUICK REFERENCE

## Available Commands

### Sync Agents
```bash
~/.claude/sync-agents.sh
```

### Verify Installation
```bash
./verify-claude-setup.sh
```

### Check TLDR Status
```bash
tldr status .
```

### Test Claude Code
```bash
claude --version
```

## Environment Variables

```bash
# Auto-push to Gitea after sync
export GITEA_REPO_URL="https://github.rommark.dev/admin/claude-code-glm-suite.git"

# Update repository agents during sync
export REPO_AGENTS_DIR="/path/to/repo/agents"
```

## Troubleshooting

### Agents not triggering?
- Check `~/.claude/agents/` directory
- Verify agent files exist and have content
- Restart Claude Code

### MCP tools not available?
- Check `~/.claude/claude_desktop_config.json`
- Verify MCP servers are installed
- Restart Claude Code

### TLDR not working?
- Run `tldr warm .` in project directory
- Check Python installation
- Verify `tldr-mcp` is in PATH

---

# 📖 ADDITIONAL RESOURCES

## Official Documentation
- **Claude Code**: https://docs.anthropic.com/en/docs/claude-code
- **Z.AI / GLM**: https://docs.z.ai/devpack/tool/claude
- **contains-studio/agents**: https://github.com/contains-studio/agents
- **@z_ai/mcp-server**: https://github.com/zai-ai/mcp-server
- **llm-tldr**: https://github.com/parcadei/llm-tldr

## Community & Support
- **Claude Code Sub-Agents**: https://docs.anthropic.com/en/docs/claude-code/sub-agents
- **Gitea Repository**: https://github.rommark.dev/admin/claude-code-glm-suite

## Changelog & Updates
- Check the repository regularly for updates
- Use `~/.claude/sync-agents.sh` to keep agents current
- Review MASTER-PROMPT.md for latest features

---

**Last Updated**: 2025-01-16
**Version**: 2.0
**Maintained By**: rommark.dev