claude-zai

🔥 Real Claude Code Plugin - z.ai provider integration with hot-reload capability!

Overview

claude-zai is a real Claude Code plugin that seamlessly integrates z.ai GLM-5 language models with Claude Code CLI. Unlike traditional wrappers, it installs as a native plugin that survives Claude Code updates and provides hot-reload capability for instant provider switching.

Key Benefits

• Real Plugin: Installs to ~/.claude/plugins/claude-zai/ - completely independent from Claude Code core
• Hot-Reload: Enable/disable z.ai without restarting Claude Code
• Update Resistant: Survives Claude Code updates without breaking
• One-Command Setup: npm install -g claude-zai - that's it!
• Secure Storage: AES-256-GCM encrypted API key storage

🚀 What's New in v2.0 - Real Plugin System

• 🎯 Real Plugin System: Native Claude Code plugin integration (~/.claude/plugins/)
• 🔒 Update Resistant: Survives Claude Code updates without breaking
• ⚡ Auto-Activation: Works immediately after npm install
• 🔥 Hot-Reload: Enable/disable z.ai without restarting Claude Code
• 🛡️ Independent Config: Separate from Claude Code settings, survives updates
• 📦 NPM Global Package: One-command installation on any machine
• 🎯 Setup Wizard: Interactive configuration for first-time users
• 🛡️ Health Checks: Comprehensive system validation and diagnostics
• 💾 Backup System: Configuration backup and restore functionality

Features

🎯 Real Plugin System (v2.0)

• Native Plugin: Integrates as a real Claude Code plugin in ~/.claude/plugins/
• Update Resistant: Completely independent from Claude Code core files
• Auto-Discovery: Claude Code automatically finds and loads the plugin
• Version Compatible: Works across different Claude Code versions
• Safe Installation: Cannot break Claude Code installation

z.ai Integration

• z.ai GLM-5 Models: Access to z.ai's advanced GLM-5 language models
• Anthropic-Compatible API: Seamless integration with Claude Code
• Hot-Reload: Enable/disable z.ai without restarting Claude Code
• Secure Storage: z.ai API keys encrypted with AES-256-GCM
• Extended Timeout: 3000 second timeout for long-running requests
• Cross-Platform: Windows, macOS, and Linux support

Advanced Features

• Event-Driven Architecture: Extensible hook system for custom integrations
• Migration Support: Automatic version migration with rollback capability
• Profile Management: Provider validation and health monitoring
• Setup Wizard: Interactive first-time configuration
• Backup System: Comprehensive backup and restore functionality

Installation

# Install from NPM (recommended)
npm install -g claude-zai

# That's it! The plugin automatically installs itself to ~/.claude/plugins/
# No manual setup required - Claude Code will detect it automatically

Automatic Installation Process

When you run npm install -g claude-zai, the plugin automatically:

1. ✅ Creates plugin directory in ~/.claude/plugins/claude-zai/
2. ✅ Generates plugin manifest and configuration
3. ✅ Registers with Claude Code plugin system
4. ✅ Sets up hooks for startup, config changes, and provider switching
5. ✅ Prepares independent configuration (survives Claude Code updates)

Manual Installation from Source

git clone https://github.com/mosaicenk/claude-zai.git
cd claude-zai
npm install
npm run build
npm run install-plugin  # Install plugin to ~/.claude/plugins/

Why Real Plugin System?

❌ Old Approach (CLI Wrapper)

• ❌ Breaks when Claude Code updates
• ❌ Requires manual reinstallation
• ❌ Modifies Claude Code core files
• ❌ Complex setup process

✅ New Approach (Real Plugin)

• ✅ Survives Claude Code updates
• ✅ One-command installation
• ✅ Zero modifications to Claude Code
• ✅ Automatic detection and activation
• ✅ Independent configuration
• ✅ Version compatibility management

Quick Start

# 1. Install plugin (automatic setup)
npm install -g claude-zai

# 2. Set your z.ai API key
claude-zai set-key

# 3. Enable z.ai provider (with hot-reload!)
claude-zai enable

# 4. Start Claude Code - it will use z.ai automatically
claude

# That's it! Your z.ai integration is ready.

Commands

Core Commands

claude-zai                    # Show z.ai status
claude-zai setup              # Run interactive setup wizard
claude-zai enable             # Enable z.ai provider (hot-reload)
claude-zai disable            # Disable z.ai, use original Claude

API Key Management

claude-zai set-key            # Set z.ai API key
claude-zai show-key           # Show masked z.ai API key
claude-zai clear-key           # Remove stored z.ai API key

System Commands

claude-zai install            # Install Claude Code integration
claude-zai uninstall          # Remove integration
claude-zai doctor             # Run health checks and diagnostics

Advanced Commands

claude-zai backup             # Create configuration backup
claude-zai restore <id>       # Restore from backup
claude-zai profile            # Show z.ai profile details
claude-zai migrate            # Run system migrations

Supported Provider

z.ai GLM-5

• Auth Method: API Key
• Hot-Reload: ✅ Supported
• Endpoint: api.z.ai/api/anthropic
• Features:
  • Anthropic-compatible API
  • Extended timeout (3000 seconds)
  • Secure API key storage
  • GLM-5 language model access

Toggle z.ai

# Enable z.ai GLM-5 models
claude-zai enable

# Disable z.ai, use original Claude
claude-zai disable

Hot-Reload Feature

🔥 New in v2.0: Enable/disable z.ai without restarting Claude Code!

# Claude Code is running with original Claude
$ claude-zai enable

✅ Hot-reloaded to z.ai (no restart needed!)

Hot-reload works by:

1. Detecting running Claude Code processes
2. Updating provider configuration in profile
3. Sending reload signal to Claude Code
4. Verifying successful switch

If hot-reload fails, the system automatically falls back to safe restart.

How the Real Plugin System Works

🎯 Plugin Discovery & Loading

1. Installation: npm install -g claude-zai creates plugin in ~/.claude/plugins/claude-zai/
2. Manifest: Plugin declares itself via manifest.json with hooks and capabilities
3. Auto-Discovery: Claude Code automatically discovers plugins on startup
4. Hook Registration: Plugin hooks are registered for lifecycle events

🔄 Plugin Lifecycle

Claude Code Startup
    ↓
Plugin Discovery (~/.claude/plugins/)
    ↓
Load Plugin Manifests
    ↓
Execute Startup Hooks ← Our plugin initializes here
    ↓
Ready for Provider Switching

🛡️ Update Resistance Strategy

• Independent Config: Plugin config in ~/.claude/plugins/claude-zai/config.json
• No Core Modifications: Zero changes to Claude Code core files
• Version Detection: Plugin adapts to different Claude Code versions
• Graceful Degradation: Falls back to safe mode if features unavailable

🔧 Hook System

The plugin responds to Claude Code events:

• onStartup: Initialize plugin when Claude Code starts
• onConfigChange: React to configuration changes
• onProviderSwitch: Handle provider switching requests
• onShutdown: Clean up when Claude Code closes

Security Architecture

Enhanced Security Model (v2.0)

🔒 Profile-Based Encrypted Storage

• API keys are never stored in settings.json
• Each provider has its own encrypted profile
• Keys are encrypted using AES-256-GCM
• Platform-specific key storage when available

Security Features:

• ✅ No plaintext API keys in any configuration file
• ✅ Encrypted profile-based storage
• ✅ Secure file permissions (0600)
• ✅ Memory sanitization for sensitive data
• ✅ Automatic security validation

Platform Storage:

• Windows: DPAPI with user-specific keys
• macOS: Keychain (via keytar)
• Linux: libsecret / GNOME Keyring (via keytar)
• Fallback: Encrypted file storage

File Structure

~/.claude/                          # Claude Code configuration
├── plugins/                       # Claude Code plugins (NEW in v2.0)
│   └── claude-zai/            # Our plugin directory
│       ├── manifest.json          # Plugin manifest
│       ├── config.json            # Plugin configuration (independent)
│       └── data/                  # Plugin data directory
│           ├── encrypted-keys.json # Encrypted API keys
│           └── migration-state.json
├── profiles/                      # Provider profiles
│   ├── active.txt                # Active provider
│   ├── zai.json                  # z.ai profile (with encrypted key)
│   ├── claude.json               # Claude profile
│   └── backups/                  # Profile backups
├── settings.json                  # Claude Code settings (NO API keys)
└── .migration-state              # Migration status

~/.local/bin/                      # Launch scripts
└── claude-zai                    # Main CLI

Key Difference in v2.0: Plugin configuration is now in ~/.claude/plugins/claude-zai/ which is completely independent from Claude Code's core configuration. This means the plugin survives Claude Code updates!

Migration & Backup

Automatic Migration

# Check if migration is needed
claude-zai doctor

# Run migration (automatic backup created)
claude-zai migrate

Backup & Restore

# Create manual backup
claude-zai backup

# List available backups
claude-zai backup --list

# Restore from backup
claude-zai restore <backup-id>

# Clean old backups (keep last 5)
claude-zai cleanup

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run locally
node dist/index.js

# Link globally for testing
npm link

# Run tests
npm test

# Run security tests
npm run test:security

Architecture

Claude Switch v2.0 features a real plugin architecture:

Plugin System Components

• Plugin Manifest: Describes plugin capabilities and hooks
• Plugin Loader: Discovers and loads plugins from ~/.claude/plugins/
• Hook System: Responds to Claude Code lifecycle events
• Config Manager: Independent plugin configuration management

Integration Layer

• Claude Code Loader: Detects Claude Code installation and version
• Event Dispatcher: Routes events to plugin hooks
• Hot-Reload Manager: Handles provider switching without restart
• Compatibility Manager: Adapts to different Claude Code versions

Security & Storage

• Encryption Layer: AES-256-GCM encryption for API keys
• Platform Storage: OS-specific secure storage (Keychain, DPAPI, etc.)
• Profile Manager: Provider profile validation and health checks
• Migration System: Safe upgrades with automatic backup

Core Systems

• Provider Abstraction: Multi-provider support with unified API
• CLI Interface: User-friendly command interface
• Event System: Extensible event-driven architecture
• Testing Framework: Comprehensive test coverage

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Troubleshooting

Plugin not showing up in Claude Code?

# Check if plugin is installed
ls -la ~/.claude/plugins/claude-zai/

# Verify manifest exists
cat ~/.claude/plugins/claude-zai/manifest.json

# Check Claude Code version compatibility
claude-zai doctor

# Reinstall plugin if needed
npm uninstall -g claude-zai
npm install -g claude-zai

Claude Code update broke the plugin?

# This shouldn't happen with v2.0! But if it does:
# Check compatibility
claude-zai doctor

# Force plugin reload
claude-zai reinstall-plugin

# Restore from backup if needed
claude-zai restore <backup-id>

Claude Code not detecting provider changes?

# Run health check
claude-zai doctor

# Try with force restart
claude-zai disable
claude-zai enable

# Check if Claude Code is running
claude-zai status

API key not working?

# Validate API key
claude-zai validate-key

# Reset and re-enter
claude-zai clear-key
claude-zai set-key

Migration issues?

# Create backup first
claude-zai backup

# Run migration with verbose output
claude-zai migrate --verbose

# Rollback if needed
claude-zai restore <backup-id>

Contributing

Contributions are welcome! Please see docs/CONTRIBUTING.md for guidelines.

Usage Examples

Basic Workflow

# 1. Install the plugin
npm install -g claude-zai

# 2. Set up your z.ai API key
claude-zai set-key

# 3. Enable z.ai provider
claude-zai enable

# 4. Start Claude Code with z.ai
claude

Advanced Usage

# Run health check
claude-zai doctor

# Check profile details
claude-zai profile

# Create backup before making changes
claude-zai backup

# Switch back to original Claude
claude-zai disable

# Restore from backup if needed
claude-zai restore backup-1234567890

Troubleshooting Examples

First-time Setup

# Run the setup wizard
claude-zai setup

# Follow the prompts:
# 1. Enter your z.ai API key
# 2. Choose to enable z.ai
# Done!

System Diagnostics

# Check if everything is working
claude-zai doctor

# The doctor will check:
# - Plugin installation
# - API key configuration
# - Claude Code installation
# - Profile files
# - Configuration security

Backup and Recovery

# Create a backup before updates
claude-zai backup

# If something goes wrong, restore
claude-zai restore backup-<timestamp>

License

MIT

Author

CTK Technologies LTD.

Links

• GitHub
• NPM
• Documentation
• Architecture
• Security