claude-code-subagents-orchestrator/docs/INSTALLATION.md

Claude Code Sub-agents Orchestrator - A powerful MCP server for orchestrating multiple AI sub-agents for complex task execution in Claude Code

# Installation Guide

## Quick Start

The fastest way to install Claude Code Subagents Orchestrator:

```bash
# Install via npm (recommended)
npm install -g claude-code-subagents-orchestrator

# Initialize MCP server
claude-orchestrator init

# Verify installation
claude-orchestrator health-check
```

## Prerequisites

### Required Software

- **Node.js**: Version 18.0.0 or higher
- **npm**: Version 8.0.0 or higher  
- **Claude Code**: Latest version from [claude.ai/code](https://claude.ai/code)

### System Requirements

- **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+)
- **Architecture**: x64 or ARM64
- **Memory**: 512MB RAM minimum, 1GB recommended
- **Disk Space**: 100MB for installation, 500MB for operation

## Installation Methods

### Method 1: NPM Installation (Recommended)

#### Global Installation
```bash
npm install -g claude-code-subagents-orchestrator
```

#### Local Installation
```bash
mkdir my-orchestrator-project
cd my-orchestrator-project
npm init -y
npm install claude-code-subagents-orchestrator
npx claude-orchestrator init
```

### Method 2: Installation Scripts

#### Linux/macOS
```bash
curl -fsSL https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.sh | bash
```

#### Windows PowerShell
```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.ps1" -OutFile "install.ps1"
.\install.ps1
```

### Method 3: Docker Installation

#### Using Docker Compose
```bash
git clone https://github.com/anthropic/claude-code-subagents-orchestrator.git
cd claude-code-subagents-orchestrator
docker-compose up -d
```

#### Direct Docker Run
```bash
docker run -d \
  --name claude-orchestrator \
  -p 3000:3000 \
  -v orchestrator_data:/app/data \
  ghcr.io/anthropic/claude-code-subagents-orchestrator:latest
```

### Method 4: Source Installation

```bash
git clone https://github.com/anthropic/claude-code-subagents-orchestrator.git
cd claude-code-subagents-orchestrator
npm install
npm run build
npm install -g .
```

## Platform-Specific Instructions

### Windows

#### Using npm
1. Install Node.js from [nodejs.org](https://nodejs.org/)
2. Open PowerShell as Administrator
3. Run: `npm install -g claude-code-subagents-orchestrator`
4. Configure: `claude-orchestrator init`

#### Using Installation Script
1. Download and run the PowerShell script:
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   Invoke-WebRequest -Uri "https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.ps1" -OutFile "install.ps1"
   .\install.ps1
   ```

#### WSL2 Support
The orchestrator works in WSL2 environments. Follow the Linux instructions within your WSL2 distribution.

### macOS

#### Using npm
```bash
# Install Node.js using Homebrew (recommended)
brew install node

# Install orchestrator
npm install -g claude-code-subagents-orchestrator

# Initialize
claude-orchestrator init
```

#### Using Installation Script
```bash
curl -fsSL https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.sh | bash
```

### Linux (Ubuntu/Debian)

#### Install Node.js
```bash
# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or using snap
sudo snap install node --classic
```

#### Install Orchestrator
```bash
npm install -g claude-code-subagents-orchestrator
claude-orchestrator init
```

### Linux (CentOS/RHEL/Fedora)

#### Install Node.js
```bash
# Using NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install nodejs npm

# Or using snap
sudo snap install node --classic
```

#### Install Orchestrator
```bash
npm install -g claude-code-subagents-orchestrator
claude-orchestrator init
```

## Post-Installation Setup

### 1. MCP Server Registration

The orchestrator automatically registers itself with Claude Code during installation. If this fails, run:

```bash
claude-orchestrator init
```

### 2. Verify Installation

```bash
# Check installation
claude-orchestrator --version

# Run health check
claude-orchestrator health-check

# List available agents
claude-orchestrator list-agents
```

### 3. Configuration

The configuration file is located at:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`

Example configuration:
```json
{
  "mcpServers": {
    "claude-code-subagents-orchestrator": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/dist/server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

## Development Installation

### For Contributors

```bash
# Clone repository
git clone https://github.com/anthropic/claude-code-subagents-orchestrator.git
cd claude-code-subagents-orchestrator

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build
```

### Development Docker Setup

```bash
# Build development image
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Run tests in container
docker-compose run orchestrator-test
```

## Environment Variables

The orchestrator supports various environment variables for configuration:

```bash
# Core settings
NODE_ENV=production          # Environment mode
LOG_LEVEL=info              # Logging level
PORT=3000                   # Server port

# Paths
DATA_DIR=/app/data          # Data directory
LOG_DIR=/app/logs           # Log directory
CONFIG_DIR=/app/config      # Config directory

# Feature flags
ENABLE_METRICS=true         # Enable metrics collection
ENABLE_CACHING=true         # Enable caching
DEBUG_MODE=false            # Debug mode
```

## Updating

### Update via npm
```bash
npm update -g claude-code-subagents-orchestrator
```

### Update via Installation Script
```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.sh | bash -s update

# Windows
.\install.ps1 -Action update
```

### Update Docker
```bash
docker-compose pull
docker-compose up -d
```

## Uninstallation

### Remove npm Installation
```bash
npm uninstall -g claude-code-subagents-orchestrator
```

### Remove via Installation Script
```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/anthropic/claude-code-subagents-orchestrator/main/scripts/install.sh | bash -s uninstall

# Windows
.\install.ps1 -Action uninstall
```

### Manual Cleanup
If automatic removal fails:

1. Remove global package: `npm uninstall -g claude-code-subagents-orchestrator`
2. Remove from Claude Code config (remove the MCP server entry)
3. Remove configuration files:
   - Windows: Delete `%APPDATA%\claude-orchestrator\`
   - macOS: Delete `~/Library/Application Support/claude-orchestrator/`
   - Linux: Delete `~/.config/claude-orchestrator/`

## Next Steps

After installation:

1. [Read the User Guide](USER_GUIDE.md)
2. [Configure your first agents](CONFIGURATION.md)
3. [Learn about troubleshooting](TROUBLESHOOTING.md)
4. [Explore advanced features](ADVANCED_USAGE.md)

## Support

If you encounter installation issues:

1. Run the health check: `claude-orchestrator health-check --verbose`
2. Check the [troubleshooting guide](TROUBLESHOOTING.md)
3. Review [common issues](FAQ.md)
4. [Open an issue](https://github.com/anthropic/claude-code-subagents-orchestrator/issues) on GitHub