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

# Claude Code Integration Guide

> Technical documentation of how 40+ agents, MCP tools, and frameworks were integrated into Claude Code

## Table of Contents

1. [Agent Integration Architecture](#agent-integration-architecture)
2. [MCP Tools Integration](#mcp-tools-integration)
3. [Ralph Framework Integration](#ralph-framework-integration)
4. [Auto-Triggering System](#auto-triggering-system)
5. [Multi-Model Support](#multi-model-support)
6. [Benefits & Use Cases](#benefits--use-cases)

---

## Agent Integration Architecture

### How Agents Work in Claude Code

Claude Code uses a **file-based agent system** where each agent is defined as a Markdown file with structured metadata and instructions.

#### Agent File Structure

```bash
~/.claude/agents/
├── engineering/
│   ├── frontend-developer.md
│   ├── backend-architect.md
│   ├── ai-engineer.md
│   └── ...
├── marketing/
│   ├── tiktok-strategist.md
│   ├── growth-hacker.md
│   └── ...
└── design/
    ├── whimsy-injector.md
    └── ...
```

#### Agent File Format

Each agent file contains:

```markdown
---
description: Specialized agent for frontend development with React, Vue, and Angular
triggers:
  - User asks for UI components
  - Frontend code needs to be written
  - Responsive design is mentioned
---

# Frontend Developer Agent

You are a frontend development specialist...

## Capabilities
- React, Vue, Angular expertise
- Responsive design
- Performance optimization
- Accessibility standards

## Approach
1. Analyze requirements
2. Choose appropriate framework
3. Implement with best practices
4. Optimize for performance
...
```

#### Integration Points

**1. File-Based Discovery**
- Claude Code scans `~/.claude/agents/` directory
- Automatically discovers all `.md` files
- Parses YAML frontmatter for metadata
- Loads agent descriptions and triggers

**2. Task Routing**
```javascript
// Claude Code internal routing (simplified)
function selectAgent(userQuery, availableAgents) {
    for (agent of availableAgents) {
        if (matchesTriggers(userQuery, agent.triggers)) {
            return agent;
        }
    }
    return defaultAgent;
}
```

**3. Context Injection**
- Agent instructions are injected into system prompt
- Agent-specific context is maintained
- Previous interactions with same agent are remembered

#### Our Integration Approach

**Created 40+ Specialized Agent Files:**
- Organized by category (engineering, marketing, product, etc.)
- Each with specific triggers and capabilities
- Optimized for 6-day development cycles
- Coordinated with studio operations workflows

**Example: frontend-developer.md**
```markdown
---
description: React/Vue/Angular specialist with responsive design expertise
triggers:
  - react component
  - frontend
  - ui/ux
  - responsive design
  - web application
---

You are a Frontend Developer agent specializing in modern web frameworks...

## Tech Stack
- React 18+ with hooks
- Vue 3 with composition API
- Angular 15+
- TypeScript
- Tailwind CSS

## Development Philosophy
- Mobile-first responsive design
- Accessibility-first (WCAG 2.1 AA)
- Performance optimization
- Component reusability
...
```

---

## MCP Tools Integration

### What is MCP (Model Context Protocol)?

MCP is an **open standard** for connecting AI models to external tools and data sources. Think of it as a "plugin system" for AI assistants.

---

### 📊 MCP Compatibility Matrix

| MCP Tool/Package | Provider | Works with Anthropic Claude | Works with Z.AI GLM | Best For |
|-----------------|----------|----------------------------|---------------------|----------|
| **@z_ai/mcp-server** | Z.AI | ✅ Yes | ✅ Yes (Optimized) | Vision analysis (8 tools) |
| **@z_ai/coding-helper** | Z.AI | ✅ Yes | ✅ Yes (Optimized) | Web search, GitHub (3 tools) |
| **llm-tldr** | parcadei | ✅ Yes | ✅ Yes | Code analysis (18 tools) |
| **Total MCP Tools** | - | **29 tools** | **29 tools** | Full compatibility |

---

### 🔍 Detailed Breakdown by Provider

#### 1. Z.AI MCP Tools (@z_ai/mcp-server)

**Developer:** Z.AI
**Package:** `@z_ai/mcp-server`
**Installation:** `npm install -g @z_ai/mcp-server`

**Compatibility:**
- ✅ **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API)
- ✅ **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (optimized integration)

**Vision Tools (8 total):**
1. `analyze_image` - General image understanding
2. `analyze_video` - Video content analysis
3. `ui_to_artifact` - Convert UI screenshots to code
4. `extract_text` - OCR text extraction
5. `diagnose_error` - Error screenshot diagnosis
6. `ui_diff_check` - Compare two UIs
7. `analyze_data_viz` - Extract insights from charts
8. `understand_diagram` - Understand technical diagrams

**Why It Works with Both:**
These tools use standard MCP protocol (STDIO/JSON-RPC) and don't rely on model-specific APIs. They work with any Claude-compatible model, including Z.AI GLM models.

---

#### 2. Z.AI Coding Helper (@z_ai/coding-helper)

**Developer:** Z.AI
**Package:** `@z_ai/coding-helper`
**Installation:** `npm install -g @z_ai/coding-helper`

**Compatibility:**
- ✅ **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API)
- ✅ **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (optimized integration)

**Web/GitHub Tools (3 total):**
1. `web-search-prime` - AI-optimized web search
2. `web-reader` - Convert web pages to markdown
3. `github-reader` - Read and analyze GitHub repositories

**Why It Works with Both:**
Standard MCP protocol tools. When used with GLM models, Z.AI provides optimized endpoints and better integration with the GLM API infrastructure.

---

#### 3. TLDR Code Analysis (llm-tldr)

**Developer:** parcadei
**Package:** `llm-tldr` (PyPI)
**Installation:** `pip install llm-tldr`

**Compatibility:**
- ✅ **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API)
- ✅ **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (via Claude Code API compatibility)

**Code Analysis Tools (18 total):**
1. `context` - LLM-ready code summaries (95% token reduction)
2. `semantic` - Semantic search by behavior (not exact text)
3. `slice` - Program slicing for debugging
4. `impact` - Impact analysis for refactoring
5. `cfg` - Control flow graphs
6. `dfg` - Data flow graphs
7. And 12 more...

**Why It Works with Both:**
TLDR is a standalone MCP server that processes code locally and returns structured data. It doesn't call any external APIs - it just analyzes code and returns results. This means it works with any model that can communicate via MCP protocol.

---

### ⚙️ Configuration Examples

#### Example 1: All MCP Tools with Anthropic Claude

`~/.claude/settings.json`:
```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-your-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}
```

`~/.claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    },
    "web-search": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"],
      "env": { "TOOL": "web-search-prime" }
    },
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    }
  }
}
```

#### Example 2: All MCP Tools with Z.AI GLM Models

`~/.claude/settings.json`:
```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-zai-api-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` (same as above):
```json
{
  "mcpServers": {
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    },
    "web-search": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"],
      "env": { "TOOL": "web-search-prime" }
    },
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    }
  }
}
```

**Key Point:** The MCP configuration is **identical** for both Anthropic and Z.AI models. The only difference is in `settings.json` (API endpoint and model names).

---

### 🎯 Summary

**All 29 MCP Tools Work with Both Models:**
- ✅ **8 Vision Tools** from @z_ai/mcp-server
- ✅ **3 Web/GitHub Tools** from @z_ai/coding-helper
- ✅ **18 Code Analysis Tools** from llm-tldr

**Why Universal Compatibility?**
1. **Standard Protocol:** All tools use MCP (STDIO/JSON-RPC)
2. **No Model-Specific APIs:** Tools don't call Claude or GLM APIs directly
3. **Local Processing:** Vision, code analysis, and web search happen locally
4. **Claude Code Compatibility:** Claude Code handles the model communication

**What's Different When Using GLM:**
- **API Endpoint:** `https://api.z.ai/api/anthropic` (instead of `https://api.anthropic.com`)
- **Model Names:** `glm-4.5-air`, `glm-4.7` (instead of `claude-haiku-4`, etc.)
- **Cost:** 90% cheaper with Z.AI GLM Coding Plan
- **Performance:** GLM-4.7 is comparable to Claude Sonnet

**Everything Else Stays the Same:**
- ✅ Same MCP tools
- ✅ Same configuration files
- ✅ Same agent functionality
- ✅ Same auto-triggering behavior

#### MCP Architecture

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Claude     │────▶│  MCP Server  │────▶│   Tool      │
│  Code       │     │  (bridge)    │     │   (API)     │
└─────────────┘     └──────────────┘     └─────────────┘
      │                    │
      ▼                    ▼
┌─────────────┐     ┌──────────────┐
│  Agent      │◀───│  Tool Output │
│  Context    │     │  (result)    │
└─────────────┘     └──────────────┘
```

#### Integration Method 1: NPM Packages

**Vision Tools (@z_ai/mcp-server)**

```bash
# Install the MCP server
npm install -g @z_ai/mcp-server
```

**Configuration (~/.claude/claude_desktop_config.json):**
```json
{
  "mcpServers": {
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    }
  }
}
```

**How It Works:**
1. Claude Code starts the MCP server on startup
2. Server exposes tools via STDIO/JSON-RPC protocol
3. When agent needs vision analysis, Claude sends request to MCP server
4. Server processes and returns structured data
5. Agent uses the data in its response

**Available Vision Tools:**
- `analyze_image` - General image understanding
- `analyze_video` - Video content analysis
- `ui_to_artifact` - Convert UI screenshots to code
- `extract_text` - OCR text extraction
- `diagnose_error` - Error screenshot diagnosis
- `ui_diff_check` - Compare two UIs
- `analyze_data_viz` - Extract insights from charts
- `understand_diagram` - Understand technical diagrams

#### Integration Method 2: Configuration-Based Tools

**Web Search, Web Reader, GitHub Reader**

These are configured via MCP server settings:

```json
{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"],
      "env": {
        "TOOL": "web-search-prime"
      }
    },
    "web-reader": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"],
      "env": {
        "TOOL": "web-reader"
      }
    },
    "zread": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"],
      "env": {
        "TOOL": "github-reader"
      }
    }
  }
}
```

#### Tool Invocation Flow

```javascript
// When an agent needs a tool

// 1. Agent identifies need
agent: "I need to search the web for latest React trends"

// 2. Claude Code routes to MCP tool
tool = mcpServers['web-search'].tools['web-search-prime']

// 3. Execute tool
result = await tool.execute({
  query: "latest React trends 2025",
  maxResults: 10
})

// 4. Return to agent
agent.receive(result)
```

#### Our MCP Integration Benefits

**Vision Capabilities:**
- Designers can show screenshots and get code
- Debugging with error screenshots
- Analyze competitor UIs
- Extract data from charts/dashboards

**Web Capabilities:**
- Real-time web search for current information
- Read documentation from URLs
- Analyze GitHub repositories without cloning

---

## Ralph Framework Integration

> **📖 Comprehensive Guide:** See [RALPH-INTEGRATION.md](RALPH-INTEGRATION.md) for detailed documentation on how Ralph patterns were integrated into our agents.

### What is Ralph?

**Ralph** is an AI assistant framework created by [iannuttall](https://github.com/iannuttall/ralph) that provides:
- Multi-agent coordination patterns
- Agent hierarchy and supervision
- Shared context and memory
- Task delegation workflows

> **Important:** Ralph is a **CLI tool** for autonomous agent loops (`npm i -g @iannuttall/ralph`), not a collection of Claude Code agents. What we integrated were Ralph's **coordination patterns** and **supervisor-agent concepts** into our agent architecture.

### How We Integrated Ralph Patterns

#### 1. Agent Hierarchy

Ralph uses a **supervisor-agent pattern** where some agents coordinate others:

```markdown
---
supervisor: true
subordinates:
  - frontend-developer
  - backend-architect
  - ui-designer
---

# Studio Producer Agent

You coordinate the development workflow...

## Coordination Responsibilities
- Assign tasks to specialized agents
- Review outputs from subordinates
- Ensure quality standards
- Manage timeline and dependencies
```

**Implementation in Claude Code:**
```bash
~/.claude/agents/
├── project-management/
│   ├── studio-producer.md        # Supervisor
│   └── ...
├── engineering/
│   ├── frontend-developer.md     # Subordinate
│   └── backend-architect.md      # Subordinate
└── design/
    └── ui-designer.md            # Subordinate
```

#### 2. Shared Context System

Ralph maintains **shared context** across agents:

```markdown
## Shared Context
- Project timeline: 6-day sprint cycle
- Current sprint goals: [loaded from shared memory]
- Team capacity: [known from studio operations]
- Technical constraints: [from architecture]
```

**Claude Code Implementation:**
- Agents reference shared project files
- Common documentation in `~/.claude/project-context.md`
- Previous agent outputs available as context

#### 3. Task Delegation

**Studio Producer** demonstrates Ralph's delegation pattern:

```
User: "Build a new user authentication feature"

Studio Producer:
├─► Frontend Developer: "Build login form UI"
├─► Backend Architect: "Design authentication API"
├─► UI Designer: "Create auth flow mockups"
├─► Test Writer/Fixer: "Write auth tests"
└─► Assembles all outputs into cohesive feature
```

**Agent File (studio-producer.md):**
```markdown
## Delegation Pattern

When receiving a feature request:
1. Break down into component tasks
2. Identify required specialist agents
3. Delegate tasks with clear requirements
4. Set dependencies and timeline
5. Review and integrate outputs
6. Ensure quality and consistency

## Task Delegation Template
```
Frontend Developer, please build [component]:
- Requirements: [spec]
- Design: [reference]
- Timeline: [6-day sprint]
- Dependencies: [API endpoints needed]

Backend Architect, please design [API]:
- Endpoints: [list]
- Auth requirements: [spec]
- Database schema: [entities]
```
```

#### 4. Agent Coordination

**Experiment Tracker** uses Ralph's coordination patterns:

```markdown
## Cross-Agent Coordination

When running an A/B test:
1. Work with Product Manager to define hypothesis
2. Coordinate with Engineering for implementation
3. Partner with Analytics for measurement
4. Use Feedback Synthesizer to analyze results
5. Report findings with Studio Producer
```

### Ralph Integration Benefits

**1. Multi-Agent Projects**
- Complex features require multiple specialists
- Coordinated workflows across agent types
- Consistent output quality

**2. Studio Operations**
- Professional project management
- Resource allocation
- Timeline coordination
- Quality assurance

**3. Knowledge Sharing**
- Agents learn from each other's outputs
- Shared best practices
- Consistent terminology

**4. Scalability**
- Easy to add new agents
- Clear hierarchy and responsibilities
- Modular agent system

---

## Auto-Triggering System

### What Are Auto-Triggers?

Auto-triggers **automatically invoke specific agents** based on events or conditions, without manual selection.

### Implementation via Hooks

**File: ~/.claude/hooks.json**

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

#### Hook 1: test-writer-fixer

**Trigger:** When code is modified or files change

```bash
# User modifies a Python file
$ echo "def new_function():" > app.py

# test-writer-fixer AUTOMATICALLY triggers
```

**Agent File:**
```markdown
---
autoTrigger: true
triggerEvents:
  - fileModified
  - codeChanged
  - testFailed
---

# Test Writer/Fixer Agent

You automatically trigger when code changes...

## Auto-Trigger Behavior
1. Detect changed files
2. Identify what needs testing
3. Write comprehensive tests
4. Run tests
5. Fix any failures
6. Report coverage
```

**Benefits:**
- Tests are always up-to-date
- No manual test writing needed
- Catches bugs immediately
- Maintains test coverage

#### Hook 2: whimsy-injector

**Trigger:** When UI code is generated

```javascript
// Frontend developer agent generates button
const button = <button>Click me</button>;

// whimsy-injector AUTOMATICALLY enhances
const enhancedButton = (
  <button className="hover:scale-105 active:scale-95 transition-transform">
    Click me
    <SparkleOnHover />
  </button>
);
```

**Agent File:**
```markdown
---
autoTrigger: true
triggerEvents:
  - uiGenerated
  - componentCreated
  - designImplemented
---

# Whimsy Injector Agent

You add delightful micro-interactions to UI designs...

## Enhancement Philosophy
- Subtle, unexpected moments of joy
- Never interfere with functionality
- Performance-conscious
- Accessible by default

## Auto-Trigger Behavior
1. Monitor for UI code generation
2. Analyze component for enhancement opportunities
3. Add delightful touches
4. Ensure accessibility maintained
5. Preserve performance
```

**Benefits:**
- Every UI has personality
- Consistent delight across projects
- No manual prompting needed
- Memorable user experiences

### Hook System Architecture

```
┌─────────────────┐
│   User Action   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────────┐
│  Event System   │────▶│  Hook Dispatcher │
│  (file change)  │     └────────┬─────────┘
└─────────────────┘              │
                                 ▼
                    ┌──────────────────────┐
                    │  test-writer-fixer   │
                    │  (auto-invoked)       │
                    └──────────────────────┘
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │  Tests written &     │
                    │  code verified        │
                    └──────────────────────┘
```

---

## Multi-Model Support

### Architecture

Claude Code supports **multiple model providers** through a unified interface:

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

### Provider Switching

**Option 1: Anthropic (Official)**
```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxx",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}
```

**Option 2: Z.AI / GLM Plan**
```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "zai-key-xxx",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "API_TIMEOUT_MS": "3000000"
  }
}
```

### Integration Benefits

**1. Cost Optimization**
- Z.AI offers 90% cost savings
- Same Claude API compatibility
- No code changes needed

**2. Redundancy**
- Switch providers instantly
- No lock-in
- Development vs production separation

**3. Model Selection**
```json
{
  "env": {
    "MODEL_DEFAULT": "claude-sonnet-4-20250514",
    "MODEL_FAST": "claude-haiku-4-20250514",
    "MODEL_EXPENSIVE": "claude-opus-4-20250514"
  }
}
```

---

## Benefits & Use Cases

### 1. Engineering Teams

**Before Claude Code + Agents:**
- Manual code writing
- Separate test writing
- Manual debugging
- Slow iteration

**After:**
- Frontend/Backend agents write code
- Test Writer/Fixer writes tests automatically
- Error diagnosis from screenshots
- 10x faster development

### 2. Marketing Teams

**Before:**
- Manual content creation
- Separate strategies per platform
- No viral optimization
- Slow content production

**After:**
- TikTok Strategist creates viral strategies
- Content Creator repurposes across platforms
- Growth Hacker designs experiments
- 5x content output

### 3. Product Teams

**Before:**
- Manual feedback analysis
- Slow sprint planning
- No trend analysis
- Reactive product decisions

**After:**
- Feedback Synthesizer analyzes user feedback
- Sprint Prioritizer plans 6-day sprints
- Trend Researcher identifies opportunities
- Data-driven decisions

### 4. Studio Operations

**Before:**
- Manual project coordination
- No resource optimization
- Poor workflow management
- Reactive operations

**After (Ralph patterns):**
- Studio Producer coordinates teams
- Experiment Tracker runs A/B tests
- Analytics Reporter provides insights
- Proactive operations

### 5. Design Teams

**Before:**
- Manual design implementation
- No accessibility consideration
- Inconsistent UI patterns
- Slow design-to-code

**After:**
- UI Designer creates components
- Whimsy Injector adds delight
- Brand Guardian ensures consistency
- Design-to-code in minutes

---

## Complete Integration Stack

```
┌─────────────────────────────────────────────────────────┐
│                   Claude Code CLI                       │
│  (Base platform - by Anthropic)                         │
└───────────────────┬─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────┐
│              Customization Suite Layer                  │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Agents     │  │  MCP Tools   │  │   Hooks      │ │
│  │  (40+ files) │  │  (15 tools)  │  │ (auto-trig.) │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────┤
│              Ralph Coordination Layer                    │
│  (Multi-agent patterns, task delegation, coordination)  │
├─────────────────────────────────────────────────────────┤
│              Multi-Model Support Layer                   │
│         (Anthropic + Z.AI/GLM Plan switching)           │
└─────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────┐
│                   External Services                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Anthropic│  │  Z.AI    │  │  GitHub  │  │   Web   │ │
│  │   API    │  │  GLM API │  │   API   │  │ Search  │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
└─────────────────────────────────────────────────────────┘
```

---

## Key Integration Insights

### 1. Modularity
- Each agent is independent
- Easy to add/remove agents
- No coupling between agents

### 2. Extensibility
- File-based system
- Markdown format
- No recompilation needed

### 3. Coordination
- Ralph patterns for complex workflows
- Clear hierarchy
- Shared context

### 4. Automation
- Hooks for auto-triggering
- Event-driven
- Passive activation

### 5. Flexibility
- Multi-model support
- Provider switching
- No lock-in

---

## Conclusion

This integration combines:
- **Claude Code** (base platform)
- **40+ specialized agents** (domain expertise)
- **15+ MCP tools** (external capabilities)
- **Ralph patterns** (coordination)
- **Auto-triggering** (automation)
- **Multi-model support** (flexibility)

The result is a **comprehensive AI development environment** that handles end-to-end software development, from planning to deployment, with specialized AI assistance at every step.

**Built for developers who ship.** 🚀