Claude-Code-Workflow/INSTALL.md

Claude Code Workflow (CCW) - Installation Guide

English | 中文

Interactive installation guide for Claude Code with Agent workflow coordination and distributed memory system.

⚡ Quick One-Line Installation

Windows (PowerShell):

Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content

Linux/macOS (Bash/Zsh):

bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)

Interactive Version Selection

After running the installation command, you'll see an interactive menu with real-time version information:

Detecting latest release and commits...
Latest stable: v4.6.0 (2025-10-19 04:27 UTC)
Latest commit: cdea58f (2025-10-19 08:15 UTC)

====================================================
            Version Selection Menu
====================================================

1) Latest Stable Release (Recommended)
   |-- Version: v4.6.0
   |-- Released: 2025-10-19 04:27 UTC
   \-- Production-ready

2) Latest Development Version
   |-- Branch: main
   |-- Commit: cdea58f
   |-- Updated: 2025-10-19 08:15 UTC
   |-- Cutting-edge features
   \-- May contain experimental changes

3) Specific Release Version
   |-- Install a specific tagged release
   \-- Recent: v4.6.0, v4.5.0, v4.4.0

====================================================

Select version to install (1-3, default: 1):

Version Options:

• Option 1 (Recommended): Latest stable release with verified production quality
• Option 2: Latest development version from main branch with newest features
• Option 3: Specific version tag for controlled deployments

💡 Pro Tip: The installer automatically detects and displays the latest version numbers and release dates from GitHub. Just press Enter to select the recommended stable release.

📂 Local Installation (Install-Claude.ps1)

For local installation without network access, use the bundled PowerShell installer:

Installation Modes:

# Interactive mode with prompts (recommended)
.\Install-Claude.ps1

# Quick install with automatic backup
.\Install-Claude.ps1 -Force -BackupAll

# Non-interactive install
.\Install-Claude.ps1 -NonInteractive -Force

Installation Options:

Mode	Description	Installs To
Global	System-wide installation (default)	~/.claude/, ~/.codex/, ~/.gemini/
Path	Custom directory + global hybrid	Local: agents/, commands/ Global: workflows/, scripts/

Backup Behavior:

• Default: Automatic backup enabled (-BackupAll)
• Disable: Use -NoBackup flag (⚠️ overwrites without backup)
• Backup location: claude-backup-{timestamp}/ in installation directory

⚠️ Important Warnings:

• -Force -BackupAll: Silent file overwrite (with backup)
• -NoBackup -Force: Permanent file overwrite (no recovery)
• Global mode modifies user profile directories

✅ Verify Installation

After installation, open Claude Code and check if the workflow commands are available by running:

/workflow:session:list

This command should be recognized in Claude Code's interface. If you see the workflow slash commands (e.g., /workflow:*, /cli:*), the installation was successful.

📝 Installation Notes:

• The installer will automatically install/update .codex/ and .gemini/ directories
• Global mode: Installs to ~/.codex and ~/.gemini
• Path mode: Installs to your specified directory (e.g., project/.codex, project/.gemini)
• Backup: Existing files are backed up by default to claude-backup-{timestamp}/
• Safety: Use interactive mode for first-time installation to review changes

Platform Requirements

• Windows: PowerShell 5.1+ or PowerShell Core 6+
• Linux/macOS: Bash/Zsh (for installer) or PowerShell Core 6+ (for manual Install-Claude.ps1)

Install PowerShell Core (if needed):

• Ubuntu/Debian: sudo apt install powershell
• macOS: brew install powershell
• Download: https://github.com/PowerShell/PowerShell

⚙️ Configuration

Tool Control System

CCW uses a configuration-based tool control system that makes external CLI tools optional rather than required. This allows you to:

• ✅ Start with Claude-only mode - Work immediately without installing additional tools
• ✅ Progressive enhancement - Add external tools selectively as needed
• ✅ Graceful degradation - Automatic fallback when tools are unavailable
• ✅ Flexible configuration - Control tool availability per project

Configuration File: ~/.claude/workflows/tool-control.yaml

tools:
  gemini:
    enabled: false  # Optional: AI analysis & documentation
  qwen:
    enabled: true   # Optional: AI architecture & code generation
  codex:
    enabled: true   # Optional: AI development & implementation

Behavior:

• When disabled: CCW automatically falls back to other enabled tools or Claude's native capabilities
• When enabled: Uses specialized tools for their specific strengths
• Default: All tools disabled - Claude-only mode works out of the box

Optional CLI Tools (Enhanced Capabilities)

While CCW works with Claude alone, installing these tools provides enhanced analysis and extended context:

System Utilities

Tool	Purpose	Installation
ripgrep (rg)	Fast code search	macOS: brew install ripgrep Linux: apt install ripgrep (Ubuntu) / dnf install ripgrep (Fedora) Windows: winget install ripgrep / choco install ripgrep / scoop install ripgrep Verify: rg --version
jq	JSON processing	macOS: brew install jq Linux: apt install jq (Ubuntu) / dnf install jq (Fedora) Windows: winget install jq / choco install jq / scoop install jq Verify: jq --version

External AI Tools

Configure these tools in ~/.claude/workflows/tool-control.yaml after installation:

Tool	Purpose	Installation
Gemini CLI	AI analysis & documentation	Follow official docs - Free quota, extended context
Codex CLI	AI development & implementation	Follow official docs - Autonomous development
Qwen Code	AI architecture & code generation	Follow official docs - Large context window

Recommended: MCP Tools (Enhanced Analysis)

MCP (Model Context Protocol) tools provide advanced codebase analysis. Recommended installation - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows.

MCP Server	Purpose	Installation Guide
Exa MCP	External API patterns & best practices	Install Guide
Chrome DevTools MCP	⚠️ Required for UI workflows - URL mode design extraction	Install Guide

Note

: Code Index MCP has been replaced by CCW's built-in CodexLens (mcp__ccw-tools__codex_lens). No additional installation required for code indexing.

⚠️ Note: Some workflows expect MCP tools to be available. Without them, you may experience:

• Slower code analysis and search operations
• Reduced context quality in some scenarios
• Fallback to less efficient traditional tools
• Potential unexpected behavior in advanced workflows

Troubleshooting

PowerShell Execution Policy (Windows)

If you get execution policy errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Workflow Commands Not Working

• Verify installation: ls ~/.claude (should show agents/, commands/, workflows/)
• Restart Claude Code after installation
• Check /workflow:session:list command is recognized

Permission Errors

• Windows: Run PowerShell as Administrator
• Linux/macOS: May need sudo for global PowerShell installation

Support

• Issues: GitHub Issues
• Getting Started: Quick Start Guide
• Documentation: Main README