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

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