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
2. MCP Tools Integration
3. Ralph Framework Integration
4. Auto-Triggering System
5. Multi-Model Support
6. 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

~/.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:

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

// 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

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

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

~/.claude/claude_desktop_config.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:

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

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

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

Configuration (~/.claude/claude_desktop_config.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:

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

// 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 for detailed documentation on how Ralph patterns were integrated into our agents.

What is Ralph?

Ralph is an AI assistant framework created by iannuttall 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:

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

~/.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:

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

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

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

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

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

# test-writer-fixer AUTOMATICALLY triggers

Agent File:

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

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

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

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

Provider Switching

Option 1: Anthropic (Official)

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxx",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

Option 2: Z.AI / GLM Plan

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

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