# Claude Code Customizations - Complete Setup Guide

This repository contains automated scripts to replicate a fully customized Claude Code environment with custom agents, MCP tools, and plugins.

## Overview of Customizations

### 🤖 Custom Agents (40+ specialized agents)

#### Engineering Agents
- **ai-engineer** - AI/ML feature implementation, LLM integration
- **backend-architect** - API design, database architecture, server-side logic
- **devops-automator** - CI/CD pipelines, infrastructure, monitoring
- **frontend-developer** - React/Vue/Angular UI development
- **mobile-app-builder** - iOS/Android React Native development
- **rapid-prototyper** - Quick MVP/prototype building (6-day cycle focused)
- **test-writer-fixer** - Automatic test writing and fixing

#### Marketing Agents
- **tiktok-strategist** - TikTok marketing and viral content strategies
- **growth-hacker** - Growth strategies and viral mechanics
- **content-creator** - Content creation for various platforms
- **instagram-curator** - Instagram content strategy
- **reddit-community-builder** - Reddit community engagement
- **twitter-engager** - Twitter engagement strategies
- **app-store-optimizer** - ASO and app store optimization

#### Product Agents
- **sprint-prioritizer** - 6-day sprint planning and feature prioritization
- **feedback-synthesizer** - User feedback analysis and insights
- **trend-researcher** - Market trend identification (TikTok/App Store focus)

#### Studio Operations Agents
- **studio-producer** - Cross-team coordination and resource allocation
- **project-shipper** - Launch coordination and go-to-market activities
- **studio-coach** - Elite performance coach for other agents
- **analytics-reporter** - Analytics and reporting
- **finance-tracker** - Financial tracking and management
- **infrastructure-maintainer** - Infrastructure maintenance
- **legal-compliance-checker** - Legal and compliance checks
- **support-responder** - Customer support responses

#### Project Management Agents
- **experiment-tracker** - A/B test and experiment tracking
- **project-shipper** - Project shipping coordination
- **studio-producer** - Studio production management

#### Testing Agents
- **test-writer-fixer** - Test writing and fixing (code change triggered)
- **api-tester** - API testing
- **performance-benchmarker** - Performance benchmarking
- **test-results-analyzer** - Test results analysis
- **tool-evaluator** - Tool evaluation
- **workflow-optimizer** - Workflow optimization

#### Design Agents
- **ui-designer** - UI design
- **ux-researcher** - UX research
- **brand-guardian** - Brand consistency
- **visual-storyteller** - Visual storytelling
- **whimsy-injector** - Add delightful/playful UI elements (auto-triggered after UI changes)

#### Bonus Agents
- **joker** - Humor and entertainment
- **studio-coach** - Performance coaching

### 🔧 MCP (Model Context Protocol) Tools

#### Vision Analysis Tools (`mcp__zai-mcp-server__`)
- **analyze_image** - General-purpose image analysis
- **analyze_video** - Video content analysis (MP4, MOV, M4V up to 8MB)
- **ui_to_artifact** - Convert UI screenshots to:
  - `code` - Generate frontend code
  - `prompt` - Generate AI prompt for recreation
  - `spec` - Extract design specifications
  - `description` - Natural language description
- **extract_text_from_screenshot** - OCR text extraction from screenshots
- **diagnose_error_screenshot** - Error message and stack trace diagnosis
- **ui_diff_check** - Compare two UI screenshots for differences
- **analyze_data_visualization** - Extract insights from charts/graphs/dashboards
- **understand_technical_diagram** - Analyze architecture/flowchart/UML/ER diagrams

#### Web & Research Tools
- **mcp__web-search-prime__webSearchPrime** - Enhanced web search with:
  - Domain filtering (whitelist/blacklist)
  - Time-based filtering (day/week/month/year)
  - Location-based results (CN/US)
  - Content size control (medium/high)

- **mcp__web-reader__webReader** - Web scraper and converter:
  - Fetch any URL
  - Convert to markdown or text
  - Image handling
  - Link and image summaries

#### GitHub Tools (`mcp__zread__`)
- **get_repo_structure** - Get GitHub repo directory structure
- **read_file** - Read files from GitHub repos
- **search_doc** - Search GitHub repo docs, issues, commits

#### Additional Tools
- **mcp__4_5v_mcp__analyze_image** - Image analysis with URL support
- **mcp__glm_camp_server__claim_glm_camp_coupon** - Claim GLM promotional rewards

### 🎯 Custom Skills

- **glm-plan-bug:case-feedback** - Submit bug/issue feedback for GLM Coding Plan
- **glm-plan-usage:usage-query** - Query GLM Coding Plan usage statistics

### 📁 Directory Structure

```
~/.claude/
├── agents/
│   ├── engineering/          # 7 engineering agents
│   ├── marketing/            # 7 marketing agents
│   ├── product/              # 3 product agents
│   ├── studio-operations/    # 8 studio operations agents
│   ├── project-management/   # 3 project management agents
│   ├── testing/              # 5 testing agents
│   ├── design/               # 5 design agents
│   └── bonus/                # 2 bonus agents
├── plugins/
│   ├── cache/                # Downloaded plugins
│   ├── marketplaces/         # Plugin marketplaces
│   ├── installed_plugins.json
│   └── known_marketplaces.json
├── hooks/                    # Custom hooks
├── settings.json             # Main settings
└── settings.local.json       # Local permissions
```

## Installation

### Option 1: Export from Existing Machine

If you have an existing machine with these customizations:

```bash
# 1. Export customizations
./export-claude-customizations.sh

# 2. Transfer the archive to new machine
scp claude-customizations-*.tar.gz user@new-machine:~/

# 3. On new machine, extract and install
tar -xzf claude-customizations-*.tar.gz
cd claude-customizations-export
./install-claude-customizations.sh
```

### Option 2: Fresh Installation

For a fresh installation on a new machine:

```bash
# 1. Download or clone the setup scripts
# 2. Run the installer
./install-claude-customizations.sh

# 3. Copy agent definitions from source (if available)
scp -r user@source:~/.claude/agents/* ~/.claude/agents/

# 4. Restart Claude Code
```

### Option 3: Manual Installation

```bash
# 1. Create directory structure
mkdir -p ~/.claude/agents/{engineering,marketing,product,studio-operations,project-management,testing,design,bonus}
mkdir -p ~/.claude/plugins/{cache,marketplaces}

# 2. Install MCP tools
npm install -g @z_ai/mcp-server @z_ai/coding-helper

# 3. Create settings.json
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_TOKEN_HERE",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "enabledPlugins": {
    "glm-plan-bug@zai-coding-plugins": true,
    "glm-plan-usage@zai-coding-plugins": true
  }
}
EOF

# 4. Copy agent files (from source or repository)
# 5. Copy plugin configurations
# 6. Restart Claude Code
```

## Verification

After installation, verify everything is working:

1. **Check agents are loaded:**
   ```bash
   ls -la ~/.claude/agents/*/
   ```

2. **Check MCP tools:**
   - Start a Claude Code session
   - The tools should be available automatically
   - Check for `mcp__zai-mcp-server__*` tools
   - Check for `mcp__web-search-prime__webSearchPrime`
   - Check for `mcp__web-reader__webReader`
   - Check for `mcp__zread__*` tools

3. **Check plugins:**
   ```bash
   cat ~/.claude/plugins/installed_plugins.json
   ```

4. **Test a custom agent:**
   ```
   Use the Task tool with subagent_type="tiktok-strategist"
   ```

## Configuration

### API Credentials

Edit `~/.claude/settings.json` and add your credentials:

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

### Permissions

Edit `~/.claude/settings.local.json` to customize allowed commands.

### Agent Customization

Each agent is defined in a `.md` file in `~/.claude/agents/<category>/`. Edit these files to customize agent behavior.

### MCP Server Configuration

MCP servers are configured through the `@z_ai/coding-helper` package. The preset MCP services include:

1. **zai-mcp-server** - Vision analysis (installed via npm/npx)
2. **web-search-prime** - Web search (HTTP endpoint)
3. **web-reader** - Web scraping (HTTP endpoint)
4. **zread** - GitHub reader (HTTP endpoint)

## Key Features

### 6-Day Development Cycle Focus

Many agents are optimized for rapid 6-day development sprints:
- **sprint-prioritizer** - Plan sprints
- **rapid-prototyper** - Quick MVPs
- **project-shipper** - Launch coordination
- **studio-producer** - Resource management

### Automatic Quality Assurance

Certain agents trigger automatically:
- **test-writer-fixer** - Auto-runs after code changes
- **whimsy-injector** - Auto-triggers after UI changes

### Viral Marketing Focus

Multiple agents for app growth:
- **tiktok-strategist** - TikTok-specific strategies
- **trend-researcher** - Identifies viral trends
- **growth-hacker** - Growth strategies

### Studio Production Workflow

Agents for team coordination:
- **studio-producer** - Cross-team coordination
- **studio-coach** - Performance coaching
- **project-shipper** - Launch management

## Troubleshooting

### MCP Tools Not Working

1. Check npm packages are installed:
   ```bash
   npm list -g @z_ai/mcp-server @z_ai/coding-helper
   ```

2. Verify settings.json has correct configuration

3. Check Claude Code is using the latest version

### Agents Not Showing

1. Verify agent files exist in `~/.claude/agents/`
2. Check file permissions
3. Restart Claude Code completely

### Plugin Issues

1. Check `~/.claude/plugins/installed_plugins.json`
2. Verify plugin cache exists
3. Re-run installation script

## Architecture

### How Custom Agents Work

Each agent is a markdown file with:
- Name and description
- System prompt/instructions
- Tool access permissions
- Trigger conditions

Agents are invoked via the Task tool:
```
Task(subagent_type="tiktok-strategist", prompt="...")
```

### How MCP Tools Work

MCP tools are registered via Model Context Protocol servers:
1. Server is defined in `@z_ai/coding-helper`
2. Server starts (stdio or HTTP)
3. Claude Code discovers available tools
4. Tools are invoked with parameters
5. Results return to Claude

### How Plugins Work

Plugins are npm packages with:
- `plugin.json` - Metadata
- `skills/` - Skill definitions
- `hooks/` - Event hooks
- `.mcp.json` - MCP server config (optional)

## Advanced Usage

### Creating Custom Agents

1. Create a new `.md` file in appropriate category
2. Follow existing agent structure
3. Restart Claude Code
4. Use via Task tool

### Adding New MCP Tools

1. Install MCP server: `npm install -g <mcp-package>`
2. Configure in settings or via `@z_ai/coding-helper`
3. Restart Claude Code
4. Tools become available automatically

### Creating Custom Skills

1. Create plugin structure
2. Add skill definitions
3. Register in `installed_plugins.json`
4. Invoke via Skill tool

## Version Information

- **Package Version:** 1.0.0
- **Claude Code Compatible:** Latest (2025+)
- **Node.js Required:** 14+
- **Platform:** Linux, macOS, WSL2

## Support and Contributions

For issues, questions, or contributions:
1. Check existing documentation
2. Review agent definitions for examples
3. Test with simple tasks first
4. Enable debug mode if needed

## License

These customizations are provided as-is for use with Claude Code.

## Changelog

### Version 1.0.0 (2025-01-15)
- Initial release
- 40+ custom agents across 8 categories
- 4 MCP tool integrations
- 2 custom skills
- Automated installation scripts
- Complete documentation

---

**Generated by Claude Code Customizations Package**
**Last Updated:** 2025-01-15