claude-code-glm-suite/MASTER-PROMPT.md

🚀 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:

# 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):

# 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):

# 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:

═══════════════════════════════════════════════════════════════════════════════

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 Agent (PROACTIVELY Auto-Triggers)

Source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

Clone the ui-ux-pro-max-skill repository:
git clone https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git /tmp/ui-ux-pro-max-skill

Install UI/UX Pro Max agent with PROACTIVELY triggers:
mkdir -p ~/.claude/agents/design
wget -O ~/.claude/agents/design/ui-ux-pro-max.md https://raw.githubusercontent.com/github.rommark.dev/admin/claude-code-glm-suite/main/agents/design/ui-ux-pro-max.md

Also install the SKILL file for enhanced compatibility:
mkdir -p ~/.claude/skills/ui-ux-pro-max
cp /tmp/ui-ux-pro-max-skill/.claude/skills/ui-ux-pro-max/SKILL.md ~/.claude/skills/ui-ux-pro-max/

### What This Provides:

**ui-ux-pro-max agent** with PROACTIVELY auto-triggering for:
- UI component creation (buttons, modals, forms, cards, navbars)
- Page design (landing pages, dashboards, pricing pages)
- UI/UX review and audits
- Style guide application (colors, typography, spacing)
- Accessibility compliance (WCAG 2.1 AA/AAA)
- Tech-stack specific patterns (React, Next.js, Vue, Tailwind, shadcn/ui)

**Comprehensive design knowledge:**
- 50+ design styles (glassmorphism, minimalism, brutalism, etc.)
- 97 color palettes by industry
- 57 font pairings with Google Fonts imports
- Accessibility standards (contrast ratios, keyboard nav, ARIA labels)
- Professional design patterns (no emoji icons, proper hover states)

**Key Features:**
- Automatic UI/UX review during design work
- Professional design patterns applied proactively
- Accessibility-first approach (WCAG 2.1 AA/AAA)
- Comprehensive styling guidelines

---

## 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:

{
  "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:

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

For Z.AI / GLM:

{
  "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:

{
  "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:

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

---

🎯 QUICK REFERENCE

Available Commands

Sync Agents

~/.claude/sync-agents.sh

Verify Installation

./verify-claude-setup.sh

Check TLDR Status

tldr status .

Test Claude Code

claude --version

Environment Variables

# 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