claude-code-glm-suite/README.md

# 🚀 Ultimate Claude Code & GLM Suite

> **40+ specialized AI agents, 15+ MCP tools, 7 PROACTIVELY auto-triggering coordinators** for Claude Code. Works with Anthropic Claude and Z.AI/GLM models (90% cost savings).

> 💡 **Tip:** Use invite token `R0K78RJKNW` for **10% OFF** Z.AI GLM Plan subscription: https://z.ai/subscribe?ic=R0K78RJKNW

[![Agents](https://img.shields.io/badge/Agents-38+-purple)](agents/)
[![PROACTIVELY](https://img.shields.io/badge/PROACTIVELY_Agents-7-green)](#-proactively-auto-coordination)
[![MCP Tools](https://img.shields.io/badge/MCP_Tools-15+-blue)](#-mcp-tools)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

---

## 🎯 What's New (January 2026)

### ✨ Latest Updates

- **📊 Agent Coordination System** - 7 PROACTIVELY coordinators automatically orchestrate 31 specialists
- **🎨 ui-ux-pro-max Integration** - Professional UI/UX agent with 50+ styles, 97 palettes, WCAG compliance
- **📝 MASTER-PROMPT.md Enhanced** - Complete workflow examples, proper markdown formatting
- **🔧 All 7 Coordinators Documented** - studio-coach, ui-ux-pro-max, whimsy-injector, test-writer-fixer, experiment-tracker, studio-producer, project-shipper
- **📚 Complete Documentation** - Workflow examples, coordination patterns, real-world use cases

### 🏗️ Architecture Overview

**38 Total Agents = 7 Coordinators + 31 Specialists**

The 7 **PROACTIVELY coordinators** auto-trigger based on context and orchestrate specialists automatically:

| Coordinator | Department | Auto-Triggers On |
|-------------|------------|-------------------|
| **ui-ux-pro-max** | Design | UI/UX design work, components, pages |
| **whimsy-injector** | Design | After UI/UX changes for delightful touches |
| **test-writer-fixer** | Engineering | After code modifications for testing |
| **experiment-tracker** | Project Management | Feature flags, A/B tests, experiments |
| **studio-producer** | Project Management | Cross-team coordination, resource conflicts |
| **project-shipper** | Project Management | Launches, releases, go-to-market activities |
| **studio-coach** | Bonus | Complex multi-agent tasks, agent confusion |

**How It Works:**
- **Automatic Path:** Coordinators auto-trigger → call specialists → coordinate workflow
- **Manual Path:** You directly invoke any specialist for precise control
- **Best of Both:** Automation when you want it, control when you need it

**Real Example:**
```
You: "I need a viral TikTok app in 2 weeks"
      ↓
[studio-coach PROACTIVELY triggers]
      ↓
Coordinates: rapid-prototyper + tiktok-strategist + frontend-developer
      ↓
[whimsy-injector PROACTIVELY triggers]
      ↓
Adds delightful touches
      ↓
[project-shipper PROACTIVELY triggers]
      ↓
Plans launch strategy
      ↓
Result: Complete app, launch-ready ✓
```

---

## 🚀 Quick Start

```bash
# Clone the repository
git clone https://github.rommark.dev/admin/claude-code-glm-suite.git
cd claude-code-glm-suite

# Run the interactive installer
chmod +x interactive-install-claude.sh
./interactive-install-claude.sh

# Follow the prompts:
# ✅ Choose model (Anthropic/Z.AI)
# ✅ Select agent categories to install
# ✅ Configure MCP tools
# ✅ Enter your API key
# ✅ Launch Claude Code
```

---

## ⚠️ IMPORTANT: For Z.AI / GLM Users

**If using the GLM Coding Plan (90% cheaper), you MUST configure GLM FIRST before using Claude Code!**

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

```bash
# Install coding helper and run setup wizard
npm install -g @z_ai/coding-helper
npx @z_ai/coding-helper init

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

# Start Claude Code with GLM
claude
```

**Manual Configuration (if you prefer):**
```bash
# Get API key: https://z.ai/
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
npm install -g @anthropic-ai/claude-code
claude
```

---

## 📋 Installation Options

### Option 1: Master Prompt (Recommended for First-Time Users)

**Copy and paste into Claude Code** - it will guide you through the entire installation step-by-step:

📄 **[MASTER-PROMPT.md](MASTER-PROMPT.md)**

**⚡ Quick Start:**
1. **If using GLM:** Configure GLM first (see above)
2. Start Claude Code: `claude`
3. Copy the prompt from MASTER-PROMPT.md (clearly marked with ✂️ COPY FROM HERE)
4. Paste into Claude Code
5. Done!

**Benefits:**
- ✅ See all steps before executing
- ✅ Easy to customize and understand
- ✅ Works entirely within Claude Code
- ✅ Includes all source repository references

### Option 2: Interactive Installation Script

```bash
git clone https://github.rommark.dev/admin/claude-code-glm-suite.git
cd claude-code-glm-suite
chmod +x interactive-install-claude.sh
./interactive-install-claude.sh
```

**Benefits:**
- ✅ Automated execution
- ✅ Menu-driven configuration
- ✅ Backup and verification built-in
- ✅ Faster for experienced users

### Option 3: Manual Installation

Follow the step-by-step guide below for full control over each component.

---

## ✨ What's Included

- **🤖 38 Custom Agents** across 8 departments
  - **7 PROACTIVELY coordinators** that auto-trigger and orchestrate specialists
  - **31 specialist agents** for domain-specific tasks
- **🔧 15+ MCP Tools** for vision, search, and GitHub integration
- **🤖 Ralph CLI Integration** (Advanced) - Autonomous agent looping with background execution
- **⚡ Intelligent Coordination** - Coordinators automatically detect context and orchestrate workflows
- **🎛️ Interactive Installation** with model selection (Anthropic/Z.AI)
- **🛡️ One-Click Setup** with comprehensive verification
- **📚 Complete Documentation** with real-world workflow examples

---

## 🤖 Agent Departments

### Engineering (7 agents)
- **AI Engineer** - ML & LLM integration, prompt engineering
- **Backend Architect** - API design, database architecture, microservices
- **DevOps Automator** - CI/CD pipelines, infrastructure as code
- **Frontend Developer** - React/Vue/Angular, responsive design
- **Mobile Builder** - iOS/Android React Native apps
- **Rapid Prototyper** - Quick MVPs in 6-day cycles
- **Test Writer/Fixer** - Auto-write and fix tests (PROACTIVELY)

### Design (6 agents)
- **UI/UX Pro Max** - Professional UI/UX design with 50+ styles, 97 palettes, WCAG (PROACTIVELY)
- **Whimsy Injector** - Delightful micro-interactions and memorable UX (PROACTIVELY)
- **Brand Guardian** - Brand consistency
- **UI Designer** - UI design and implementation
- **UX Researcher** - User experience research
- **Visual Storyteller** - Visual communication

### Project Management (3 agents)
- **Experiment Tracker** - A/B test tracking and metrics (PROACTIVELY)
- **Project Shipper** - Launch coordination and go-to-market (PROACTIVELY)
- **Studio Producer** - Cross-team coordination and resources (PROACTIVELY)

### Product (3 agents)
- **Feedback Synthesizer** - User feedback analysis
- **Sprint Prioritizer** - 6-day sprint planning
- **Trend Researcher** - Market trend analysis

### Marketing (7 agents)
- **TikTok Strategist** - Viral TikTok marketing strategies
- **Growth Hacker** - Growth strategies and user acquisition
- **Content Creator** - Multi-platform content creation
- **Instagram Curator** - Instagram strategy and engagement
- **Reddit Builder** - Reddit community building
- **Twitter Engager** - Twitter strategy and tactics
- **App Store Optimizer** - ASO optimization

### Studio Operations (5 agents)
- **Analytics Reporter** - Data analysis and reporting
- **Finance Tracker** - Financial tracking
- **Infrastructure Maintainer** - Infrastructure management
- **Legal Compliance Checker** - Compliance checks
- **Support Responder** - Customer support automation

### Testing (5 agents)
- **API Tester** - API testing
- **Performance Benchmarker** - Performance testing
- **Test Results Analyzer** - Test analysis
- **Tool Evaluator** - Tool evaluation
- **Workflow Optimizer** - Workflow optimization

### Bonus (2 agents)
- **Studio Coach** - Team coaching and motivation for complex tasks (PROACTIVELY)
- **Joker** - Humor and team morale

---

## 🎯 PROACTIVELY Auto-Coordination

### How It Works

The 7 PROACTIVELY coordinators automatically orchestrate the 31 specialists based on context:

**Two Pathways:**

1. **Automatic** (Recommended)
   - Coordinators auto-trigger based on context
   - Call appropriate specialists
   - Coordinate multi-agent workflows
   - Ensure quality and completeness

2. **Direct**
   - Manually invoke any specialist
   - Precise control over specific tasks
   - Use when you need specific expertise

### The 7 PROACTIVELY Coordinators

#### 1. ui-ux-pro-max (Design)
**Triggers on:** UI/UX design work, components, pages, dashboards

**Provides:**
- Professional design patterns
- 50+ design styles (glassmorphism, minimalism, brutalism, etc.)
- 97 color palettes by industry
- 57 font pairings with Google Fonts
- WCAG 2.1 AA/AAA accessibility compliance
- Tech-stack specific patterns (React, Next.js, Vue, Tailwind, shadcn/ui)

#### 2. whimsy-injector (Design)
**Triggers after:** UI/UX changes, new components, feature completion

**Provides:**
- Delightful micro-interactions
- Memorable user moments
- Playful animations
- Engaging empty states
- Celebratory success states

#### 3. test-writer-fixer (Engineering)
**Triggers after:** Code modifications, refactoring, bug fixes

**Provides:**
- Comprehensive test coverage
- Unit, integration, and E2E tests
- Failure analysis and repair
- Test suite health maintenance
- Edge case coverage

#### 4. experiment-tracker (Project Management)
**Triggers on:** Feature flags, A/B tests, experiments, product decisions

**Provides:**
- Experiment design and setup
- Success metrics definition
- A/B test tracking
- Statistical significance calculation
- Data-driven decision support

#### 5. studio-producer (Project Management)
**Triggers on:** Team collaboration, resource conflicts, workflow issues

**Provides:**
- Cross-team coordination
- Resource allocation optimization
- Workflow improvement
- Dependency management
- Sprint planning support

#### 6. project-shipper (Project Management)
**Triggers on:** Releases, launches, go-to-market, shipping milestones

**Provides:**
- Launch planning and coordination
- Release calendar management
- Go-to-market strategy
- Stakeholder communication
- Post-launch monitoring

#### 7. studio-coach (Bonus)
**Triggers on:** Complex projects, multi-agent tasks, agent confusion

**Provides:**
- Elite performance coaching
- Multi-agent coordination
- Motivation and alignment
- Problem-solving guidance
- Best practices enforcement

### Real Workflow Example

```
You: "I need a viral TikTok app in 2 weeks"
      ↓
[studio-coach PROACTIVELY triggers]
      ↓
Analyzes complexity and coordinates:
  → rapid-prototyper builds MVP
  → tiktok-strategist plans viral features
  → frontend-developer builds UI
      ↓
[whimsy-injector PROACTIVELY triggers]
      ↓
Adds delightful touches and micro-interactions
      ↓
[project-shipper PROACTIVELY triggers]
      ↓
Plans launch strategy and coordinates release
      ↓
Result: Complete viral app, launch-ready, in 2 weeks ✓
```

**Key Benefits:**
- ✅ No manual orchestration required
- ✅ Automatic quality gates (testing, UX, launches)
- ✅ Intelligent specialist selection
- ✅ Seamless multi-agent workflows
- ✅ Consistent delivery quality

---

## 🤖 Ralph CLI Integration (Advanced)

**🔗 Source:** [@iannuttall/ralph](https://github.com/iannuttall/ralph)

> **⚠️ Advanced Feature:** Ralph CLI provides autonomous agent looping for complex, multi-hour development sessions. It's optional but powerful for "fire and forget" workflows.

### What Ralph CLI Does

**PROACTIVELY Agents** = Quick coordination (single interaction)
**Ralph CLI** = Autonomous looping (multi-iteration, background execution)

Ralph CLI runs in the **background** (non-blocking), allowing you to continue working in Claude Code while it autonomously completes complex tasks.

### How It Works

```
1. You request: "Build a TikTok app in 2 weeks"
      ↓
2. Hook detects agent request
      ↓
3. Hook spawns Ralph in BACKGROUND (non-blocking)
      ↓
4. Claude Code immediately continues ← You keep working!
      ↓
5. Ralph autonomously loops in background:
   - Iteration 1: rapid-prototyper builds MVP
   - Iteration 2: tiktok-strategist plans viral features
   - Iteration 3: frontend-developer builds UI
   - Continues until complete or max iterations reached
      ↓
6. Monitor Ralph: tail -f ~/.claude/ralph-output.log
```

### Key Features

| Feature | Description |
|---------|-------------|
| **Background Execution** | Runs as background process (NON-BLOCKING) |
| **Auto-Spawning** | Hook automatically starts Ralph when needed |
| **Process Tracking** | PID file for monitoring and control |
| **Lock Mechanism** | Prevents duplicate Ralph instances |
| **Real-time Logging** | Monitor progress: `tail -f ~/.claude/ralph-output.log` |
| **Persistent State** | State preserved in `~/.claude/ralph-loop.local.md` |

### Control Modes

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

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

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

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

### Monitoring & Control

```bash
# Monitor Ralph's output in real-time
tail -f ~/.claude/ralph-output.log

# Check if Ralph is running
cat ~/.claude/ralph.pid

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

# View trigger history
cat ~/.claude/ralph-trigger.log
```

### Real-Life Example

**Scenario:** You need to build a complex feature while handling other tasks.

```bash
You: "Use the ai-engineer to implement a machine learning pipeline"

[Hook triggers automatically]

🔄 Ralph CLI auto-started in background
   PID: 12345
   Agent: ai-engineer
   Monitor: tail -f ~/.claude/ralph-output.log

Claude: "I've delegated the ML pipeline to Ralph, which is now
         working autonomously in the background (20-30 min expected).
         I'm still available to help with other tasks!"

You: "Perfect. While Ralph works on the ML pipeline, can you help me
       write unit tests for the authentication module?"

Claude: "Absolutely! Let's write those tests..."
[You work on tests while Ralph builds the ML pipeline in background]
```

### Ralph vs PROACTIVELY Agents

| Feature | Ralph CLI (Background) | PROACTIVELY Agents |
|---------|------------------------|-------------------|
| **Execution** | Multi-loop, background | Single interaction |
| **Blocking** | NON-BLOCKING | Blocking (waits) |
| **State** | File + log | Context only |
| **Control** | Manual stop (PID) | Automatic completion |
| **Best For** | Large projects, overnight | Quick tasks, collaboration |

### Installation

Ralph CLI is available as an **optional** installation step in both:
- **MASTER-PROMPT.md** (Step 6)
- **interactive-install-claude.sh** (Step 6: Ralph CLI Selection)

**To install:**
```bash
npm install -g @iannuttall/ralph
```

**To enable auto-trigger:**
```bash
# The installer creates the hook automatically
# Or manually: Follow Step 6 in MASTER-PROMPT.md
```

### When to Use Ralph CLI

✅ **Use Ralph CLI for:**
- Complex multi-step projects (2+ hours)
- "Fire and forget" autonomous coding
- Overnight builds/refactors
- Large-scale refactoring
- Multi-feature implementations

❌ **Use PROACTIVELY agents for:**
- Quick tasks (minutes)
- Human collaboration needed
- Design discussions
- Code reviews
- Quick fixes

**You can use BOTH together** - Set `RALPH_AUTO_MODE="agents"` for a hybrid approach where Ralph assists with big tasks while PROACTIVELY agents handle quick coordination.

---

## 🔧 MCP Tools

### Vision Tools (8 tools)
| Tool | Function | Input |
|------|----------|-------|
| `analyze_image` | General image analysis | PNG, JPG, JPEG |
| `analyze_video` | Video content analysis | MP4, MOV, M4V |
| `ui_to_artifact` | UI screenshot to code | Screenshots |
| `extract_text` | OCR text extraction | Any image |
| `diagnose_error` | Error screenshot diagnosis | Error screenshots |
| `ui_diff_check` | Compare UI screenshots | Before/after |
| `analyze_data_viz` | Data visualization insights | Dashboards, charts |
| `understand_diagram` | Technical diagram analysis | UML, flowcharts |

### Web & GitHub Tools
| Tool | Function | Source |
|------|----------|--------|
| `web-search-prime` | AI-optimized web search | Real-time information |
| `web-reader` | Web page to markdown conversion | Documentation access |
| `zread` | GitHub repository reader | Codebase analysis |
| `@z_ai/mcp-server` | Vision and analysis tools | [@z_ai/mcp-server](https://github.com/zai-ai/mcp-server) |
| `@z_ai/coding-helper` | Web and GitHub integration | [@z_ai/coding-helper](https://github.com/zai-ai/mcp-server) |

---

## 📚 Documentation

- **[MASTER-PROMPT.md](MASTER-PROMPT.md)** - Copy-paste installation prompt with complete workflow examples
- **[docs/workflow-example-pro.html](docs/workflow-example-pro.html)** - PRO-level workflow visualization
- **[docs/coordination-system-pro.html](docs/coordination-system-pro.html)** - Complete coordination system explanation
- **[docs/AUTO-TRIGGER-INTEGRATION-REPORT.md](docs/AUTO-TRIGGER-INTEGRATION-REPORT.md)** - Complete auto-trigger verification report

---

## 📖 Complete Source Guide

This suite integrates **7 major open-source projects**:

### 1. contains-studio/agents 🎭
**Source:** https://github.com/contains-studio/agents
**Provides:** 38 specialized agents with PROACTIVELY auto-triggering
**Key Innovation:** Context-aware agent selection system

### 2. @z_ai/mcp-server 🖼️
**Source:** https://github.com/zai-ai/mcp-server
**Provides:** 8 vision tools for images, videos, diagrams
**Key Feature:** Understand visual content for debugging and design

### 3. @z_ai/coding-helper 🌐
**Source:** https://github.com/zai-ai/mcp-server
**Provides:** Web search, GitHub integration, GLM setup wizard
**Key Feature:** Interactive configuration and real-time information

### 4. llm-tldr 📊
**Source:** https://github.com/parcadei/llm-tldr
**Provides:** 95% token reduction via 5-layer code analysis
**Key Feature:** Semantic search and impact analysis

### 5. ui-ux-pro-max-skill 🎨
**Source:** https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
**Provides:** Professional UI/UX design agent with comprehensive patterns
**Key Feature:** PROACTIVELY auto-triggering for all design work

### 6. @iannuttall/ralph 🤖
**Source:** https://github.com/iannuttall/ralph
**Provides:** Autonomous agent looping with background execution
**Key Feature:** "Fire and forget" multi-iteration development

### 7. claude-codex-settings 📋
**Source:** https://github.com/fcakyon/claude-codex-settings
**Provides:** MCP configuration best practices (reference)
**Key Feature:** Proven integration patterns

---

## 🎯 Real-Life Impact: Before vs After

| Scenario | Without Suite | With Suite | Impact |
|----------|--------------|-----------|--------|
| **Debugging Errors** | Paste text manually, miss context | Upload screenshot → Instant diagnosis | 5x faster |
| **Implementing UI** | Describe in words, iterate 10+ times | Upload design → Exact code generated | 10x faster |
| **Understanding Code** | Read files manually, hit token limits | TLDR 5-layer analysis, 95% token savings | 20x faster |
| **Writing Tests** | Write manually, forget often | Auto-triggered after every code change | Always tested |
| **Code Search** | grep for exact names | Semantic search by behavior | Finds by intent |
| **Web Research** | Outdated training data | Real-time web search | Always current |
| **Refactoring** | Risk breaking changes | Impact analysis, safe refactoring | Zero breaking changes |
| **Multi-Agent Tasks** | Manual orchestration | Automatic coordination | Hands-free delivery |

---

## 🤝 Community & Contributing

This suite is **100% open source** and available on [GitHub](https://github.rommark.dev/admin/claude-code-glm-suite).

- ⭐ Star the repo
- 🐛 Report issues
- 🔄 Submit pull requests
- 💡 Contribute your own agents!

---

## 📝 License

MIT License - Feel free to use and modify for your needs.

---

**Built for developers who ship.** 🚀