/add-parallel

Add Parallel AI Integration

Adds Parallel AI MCP integration to ClaudeClaw for advanced web research capabilities.

What This Adds

• **Quick Search** - Fast web lookups using Parallel Search API (free to use)
• **Deep Research** - Comprehensive analysis using Parallel Task API (asks permission)
• **Non-blocking Design** - Uses ClaudeClaw scheduler for result polling (no container blocking)

Prerequisites

User must have: 1. Parallel AI API key from https://platform.parallel.ai 2. ClaudeClaw already set up and running 3. Docker installed and running

Implementation Steps

Run all steps automatically. Only pause for user input when explicitly needed.

1. Get Parallel AI API Key

Use `AskUserQuestion: Do you have a Parallel AI API key, or should I help you get one?`

**If they have one:** Collect it now.

**If they need one:** Tell them: > 1. Go to https://platform.parallel.ai > 2. Sign up or log in > 3. Navigate to API Keys section > 4. Create a new API key > 5. Copy the key and paste it here

Wait for the API key.

2. Add API Key to Environment

Add `PARALLEL_API_KEY` to `.env`:

# Check if .env exists, create if not
if [ ! -f .env ]; then
    touch .env
fi

# Add PARALLEL_API_KEY if not already present
if ! grep -q "PARALLEL_API_KEY=" .env; then
    echo "PARALLEL_API_KEY=${API_KEY_FROM_USER}" >> .env
    echo "✓ Added PARALLEL_API_KEY to .env"
else
    # Update existing key
    sed -i.bak "s/^PARALLEL_API_KEY=.*/PARALLEL_API_KEY=${API_KEY_FROM_USER}/" .env
    echo "✓ Updated PARALLEL_API_KEY in .env"
fi

Verify:

grep "PARALLEL_API_KEY" .env | head -c 50

3. Update Container Runner

Add `PARALLEL_API_KEY` to allowed environment variables in `src/orchestrator/container-runner.ts`:

Find the line:

const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];

Replace with:

const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'PARALLEL_API_KEY'];

4. Configure MCP Servers in Agent Runner

Update `agent/runner/src/index.ts`:

Find the section where `mcpServers` is configured (around line 237-252):

const mcpServers: Record<string, any> = {
  claudeclaw: ipcMcp
};

Add Parallel AI MCP servers after the claudeclaw server:

const mcpServers: Record<string, any> = {
  claudeclaw: ipcMcp
};

// Add Parallel AI MCP servers if API key is available
const parallelApiKey = process.env.PARALLEL_API_KEY;
if (parallelApiKey) {
  mcpServers['parallel-search'] = {
    type: 'http',  // REQUIRED: Must specify type for HTTP MCP servers
    url: 'https://search-mcp.parallel.ai/mcp',
    headers: {
      'Authorization': `Bearer ${parallelApiKey}`
    }
  };
  mcpServers['parallel-task'] = {
    type: 'http',  // REQUIRED: Must specify type for HTTP MCP servers  
    url: 'https://task-mcp.parallel.ai/mcp',
    headers: {
      'Authorization': `Bearer ${parallelApiKey}`
    }
  };
  log('Parallel AI MCP servers configured');
} else {
  log('PARALLEL_API_KEY not set, skipping Parallel AI integration');
}

Also update the `allowedTools` array to include Parallel MCP tools (around line 242-248):

allowedTools: [
  'Bash',
  'Read', 'Write', 'Edit', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'mcp__claudeclaw__*',
  'mcp__parallel-search__*',
  'mcp__parallel-task__*'
],

5. Add Usage Instructions to CLAUDE.md

Add Parallel AI usage instructions to `groups/main/CLAUDE.md`:

Find the "## What You Can Do" section and add after the existing bullet points:

- Use Parallel AI for web research and deep learning tasks

Then add a new section after "## What You Can Do":

## Web Research Tools

You have access to two Parallel AI research tools:

### Quick Web Search (`mcp__parallel-search__search`)
**When to use:** Freely use for factual lookups, current events, definitions, recent information, or verifying facts.

**Examples:**
- "Who invented the transistor?"
- "What's the latest news about quantum computing?"
- "When was the UN founded?"
- "What are the top programming languages in 2026?"

**Speed:** Fast (2-5 seconds)
**Cost:** Low
**Permission:** Not needed - use whenever it helps answer the question

### Deep Research (`mcp__parallel-task__create_task_run`)
**When to use:** Comprehensive analysis, learning about complex topics, comparing concepts, historical overviews, or structured research.

**Examples:**
- "Explain the development of quantum mechanics from 1900-1930"
- "Compare the literary styles of Hemingway and Faulkner"
- "Research the evolution of jazz from bebop to fusion"
- "Analyze the causes of the French Revolution"

**Speed:** Slower (1-20 minutes depending on depth)
**Cost:** Higher (varies by processor tier)
**Permission:** ALWAYS use `AskUserQuestion` before using this tool

**How to ask permission:**

AskUserQuestion: I can do deep research on [topic] using Parallel's Task API. This will take 2-5 minutes and provide comprehensive analysis with citations. Should I proceed?

**After permission - DO NOT BLOCK! Use scheduler instead:**

1. Create the task using `mcp__parallel-task__create_task_run`
2. Get the `run_id` from the response
3. Create a polling scheduled task using `mcp__claudeclaw__schedule_task`:

Prompt: "Check Parallel AI task run [run_id] and send results when ready.

1. Use the Parallel Task MCP to check the task status 2. If status is 'completed', extract the results 3. Send results to user with mcp__claudeclaw__send_message 4. Use mcp__claudeclaw__complete_scheduled_task to mark this task as done

If status is still 'running' or 'pending', do nothing (task will run again in 30s). If status is 'failed', send error message and complete the task."

Schedule: interval every 30 seconds Context mode: isolated

4. Send acknowledgment with tracking link
5. Exit immediately - scheduler handles the rest

### Choosing Between Them

**Use Search when:**
- Qu