@hivetechs/hive-ai/CLAUDE_CODE_INTEGRATION.md

Real-time streaming AI consensus platform with HTTP+SSE MCP integration for Claude Code, VS Code, Cursor, and Windsurf - powered by OpenRouter's unified API

# Hive AI Integration with Claude Code

This guide shows how to integrate Hive AI with Claude Code using the Model Context Protocol (MCP), enabling you to use Hive AI's 4-stage consensus, analytics, and setup capabilities directly within your Claude Code sessions.

## Overview

Hive AI provides an MCP server that exposes five powerful tools to Claude Code:

- **`hive_admin`** - Complete setup and configuration (license, OpenRouter API)
- **`hive_consensus`** - Run 4-stage AI consensus on any question
- **`hive_analytics`** - Get performance metrics and usage data
- **`hive_profiles`** - Manage consensus profiles and configurations
- **`hive_system`** - Get system information and health status

## Quick Setup

### Method 1: Using Claude Code CLI (Recommended)

1. **Install Hive AI globally:**
   ```bash
   npm install -g @hivetechs/hive-ai
   ```

2. **Add to Claude Code using the CLI:**
   ```bash
   claude mcp add hive-ai -s user -- hive mcp-server start
   ```

3. **Verify installation:**
   ```bash
   claude mcp list
   ```

4. **Start Claude Code:**
   ```bash
   claude
   ```

### Method 2: Manual Configuration

1. **Install Hive AI globally:**
   ```bash
   npm install -g @hivetechs/hive-ai
   ```

2. **Find your Claude Code config file:**
   - **macOS:** `~/.claude.json`
   - **Linux:** `~/.claude.json`
   - **Windows:** `%USERPROFILE%\.claude.json`

3. **Edit the config file:**
   ```json
   {
     "mcpServers": {
       "hive-ai": {
         "type": "stdio",
         "command": "hive",
         "args": ["mcp-server", "start"],
         "env": {}
       }
     }
   }
   ```

4. **Restart Claude Code to load the server**

## First-Time Setup in Claude Code

Once the MCP server is configured, you can set up Hive AI completely within Claude Code:

### Step 1: Check Status
```
Use the hive_admin tool with action "status" to check current setup
```

### Step 2: Configure License
```
Use the hive_admin tool with:
- action: "configure_license" 
- license_key: "your-hive-license-key"
```

### Step 3: Configure OpenRouter
```
Use the hive_admin tool with:
- action: "configure_openrouter"
- openrouter_api_key: "sk-or-v1-your-key-here"
```

### Step 4: Verify Setup
```
Use the hive_admin tool with action "test_connection" to verify everything works
```

## Using Hive AI Tools in Claude Code

### Running AI Consensus

Ask Claude Code to run consensus on any question:

```
Can you run a consensus analysis on "how do I optimize React performance for large datasets"?
```

Claude Code will use the `hive_consensus` tool with parameters like:
- **question:** "how do I optimize React performance for large datasets"
- **mode:** "auto" (or "manual" for profile selection)
- **streaming:** true (always enabled for better UX)

💡 **Important for Claude Code Users:** After running consensus, press **Ctrl+R** to expand and view the complete detailed results. This will show you the full 4-stage analysis instead of the collapsed summary view.

### Getting Analytics

Request performance metrics and usage data:

```
Show me analytics for the last 24 hours using hive_analytics
```

### Managing Profiles

List or configure consensus profiles:

```
What consensus profiles are available? Use hive_profiles to show me.
```

### System Health

Check system status and configuration:

```
Check the health status of Hive AI using hive_system
```

## Advanced Configuration

### Multiple Scopes

You can configure Hive AI at different scopes:

- **Project-specific:** `claude mcp add hive-ai -s project -- hive mcp-server start`
- **User-wide:** `claude mcp add hive-ai -s user -- hive mcp-server start`
- **System-wide:** `claude mcp add hive-ai -s system -- hive mcp-server start`

### Environment Variables

If you need to pass environment variables:

```bash
claude mcp add hive-ai -s user -e HIVE_DEBUG=true -- hive mcp-server start
```

### Custom Configuration

For advanced setups, edit `.claude.json` directly:

```json
{
  "mcpServers": {
    "hive-ai": {
      "type": "stdio",
      "command": "hive",
      "args": ["mcp-server", "start"],
      "env": {
        "HIVE_STREAMING": "true",
        "HIVE_DEBUG": "false"
      }
    }
  }
}
```

## Troubleshooting

### Check MCP Server Status

1. **List installed servers:**
   ```bash
   claude mcp list
   ```

2. **Check if Hive AI is running:**
   ```
   Use hive_system tool with info_type "status"
   ```

3. **Test connections:**
   ```
   Use hive_admin tool with action "test_connection"
   ```

### Debug Mode

Launch Claude Code with debug mode to see MCP communication:

```bash
claude --mcp-debug
```

### Common Issues

1. **"Server not found" error:**
   - Ensure Hive AI is installed globally: `npm list -g @hivetechs/hive-ai`
   - Check the command path in your MCP config

2. **"License required" error:**
   - Use `hive_admin` tool with `configure_license` action
   - Get a license at: https://hivetechs.io/pricing

3. **"OpenRouter not configured" error:**
   - Use `hive_admin` tool with `configure_openrouter` action
   - Get an API key at: https://openrouter.ai/keys

## Integration Examples

### Code Review Workflow

```
Please review this React component and suggest improvements using Hive AI consensus:

[paste your code]

Use hive_consensus to get multiple model perspectives on code quality, performance, and best practices.
```

### Architecture Analysis

```
I'm designing a microservices architecture for an e-commerce platform. 

Use hive_consensus to analyze the trade-offs between different approaches and recommend the best architecture pattern.
```

### Performance Optimization

```
My application is experiencing slow load times. Here's the performance data:

[paste performance metrics]

Use hive_consensus to identify bottlenecks and provide optimization strategies.
```

## Benefits of Claude Code Integration

1. **Seamless Workflow:** Access Hive AI without leaving Claude Code
2. **Complete Setup:** Configure everything through MCP tools
3. **Real-time Streaming:** See consensus pipeline progress live
4. **Rich Context:** Claude Code can use consensus results in broader analysis
5. **No Context Switching:** Stay in your coding assistant environment

## Getting Help

- **Hive AI Documentation:** https://hivetechs.io/docs
- **Claude Code MCP Guide:** https://docs.anthropic.com/en/docs/claude-code
- **MCP Specification:** https://modelcontextprotocol.io/
- **Support:** https://github.com/hivetechs-collective/hive.ai/issues

## Next Steps

1. Install and configure Hive AI in Claude Code
2. Run your first consensus query
3. Explore analytics and profile management
4. Integrate Hive AI into your development workflow
5. Share feedback and suggest improvements

---

*This integration brings together the power of Hive AI's multi-model consensus with Claude Code's intelligent development assistance, creating a seamless AI-powered coding experience.*