Guides
Using with Claude Code

Using Hydra with Claude Code

Integrate Hydra workflows with Claude Code for powerful AI-assisted development.

Overview

Claude Code uses the sub-agent pattern to execute Hydra workflows. Each step can spawn a specialized sub-agent with specific capabilities.

Orchestrator (Main Agent)
├── Sub-agent: Bug Analyzer
├── Sub-agent: Code Fixer
└── Sub-agent: Test Writer

Setup

1. Deploy Your Workflow

  1. Create a workflow in the Hydra Dashboard (opens in a new tab)
  2. Click Deploy
  3. Select Claude Code as the target adapter
  4. Copy the MCP endpoint URL

2. Configure Claude Code

Add the Hydra MCP server to your Claude Code configuration:

Location: ~/.config/claude-code/config.json

{
  "mcpServers": {
    "hydra": {
      "url": "YOUR_MCP_ENDPOINT_URL"
    }
  }
}

Replace YOUR_MCP_ENDPOINT_URL with the MCP endpoint from your deployment details (found in Dashboard → Deployments).

3. Restart Claude Code

After updating the configuration, restart Claude Code to load the new MCP server.

Running Workflows

Basic Usage

Simply tell Claude Code to run your workflow:

Run the Bug Fix workflow

Claude will:

  1. Fetch the workflow from Hydra
  2. Parse the manifest
  3. Execute each step in order
  4. Spawn sub-agents for parallel steps

With Context

Provide additional context:

Run the Bug Fix workflow on the authentication module.
The bug is in src/auth/login.ts - users can't log in with special characters in passwords.

Listing Workflows

List my available Hydra workflows

Adapter Configuration

Sub-Agent Mode (Default)

Best for complex workflows with specialized steps:

{
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": {
        "spawn_agents_per_step": true,
        "max_parallel_agents": 3
      }
    }
  }
}

How it works:

  • Each step spawns a dedicated sub-agent
  • Sub-agents have focused capabilities
  • Parallel steps run concurrently (up to max_parallel_agents)

Sequential Mode

For simpler workflows that should run linearly:

{
  "adapters": {
    "claude": {
      "mode": "sequential"
    }
  }
}

How it works:

  • All steps run in the main agent
  • No sub-agent spawning
  • Steps execute one at a time

Parallel Mode

For workflows with many independent steps:

{
  "adapters": {
    "claude": {
      "mode": "parallel",
      "config": {
        "max_parallel_agents": 5
      }
    }
  }
}

Action Mappings

How HMS actions translate to Claude Code tools:

HMS ActionClaude Code Tools
analyze_codeRead, Grep, Glob
edit_fileEdit
edit_filesEdit + Task (sub-agent)
generate_codeWrite
generate_testsWrite + Bash
execute_commandBash
search_referencesGrep, Glob
design_architectureRead, Write
review_and_commitBash (git commands)

Example: Bug Fix Workflow

Manifest

{
  "name": "Bug Fix Workflow",
  "intent": "Find and fix a bug with comprehensive testing",
  "steps": [
    {
      "id": "analyze",
      "name": "Analyze the bug",
      "action": "analyze_code",
      "agent": "bug_analyzer"
    },
    {
      "id": "fix",
      "name": "Implement fix",
      "action": "edit_file",
      "depends_on": ["analyze"]
    },
    {
      "id": "test",
      "name": "Write tests",
      "action": "generate_tests",
      "depends_on": ["fix"]
    }
  ],
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": {
        "spawn_agents_per_step": true
      }
    }
  }
}

Generated Claude Prompt

You are the orchestrator for "Bug Fix Workflow".
Intent: Find and fix a bug with comprehensive testing

## Workflow Steps

Step 1: Analyze the bug
Spawn sub-agent "bug_analyzer" to:
- Use Read and Grep tools to analyze the codebase
- Identify the root cause of the bug
- Report findings

Step 2: Implement fix
After Step 1 completes:
- Use Edit tool to modify the affected files
- Implement the fix based on analysis

Step 3: Write tests
After Step 2 completes:
- Use Write tool to create test files
- Use Bash to run the test suite
- Ensure the fix is verified

Execute steps in order, reporting progress after each.

Best Practices

1. Use Agent Specialization

{
  "agent": "security_expert",
  "parameters": {
    "focus": "OWASP vulnerabilities"
  }
}

2. Set Parallel Limits

For large workflows, limit concurrent agents:

{
  "config": {
    "max_parallel_agents": 3
  }
}

3. Provide Clear Focus

{
  "parameters": {
    "focus": "performance optimization, avoid breaking changes"
  }
}

4. Use Extended Context for Large Codebases

{
  "config": {
    "context_window": "extended"
  }
}

Troubleshooting

Workflow Not Found

  • Verify your deployment ID is correct
  • Check that Claude adapter is enabled in the deployment
  • Ensure your API key has access to the workflow

Sub-agents Not Spawning

  • Confirm mode: "sub_agent" is set
  • Check spawn_agents_per_step: true
  • Verify the step has an agent field

Steps Running Out of Order

  • Check depends_on arrays are correct
  • Ensure no circular dependencies
  • Review the execution plan in the workflow editor

Next Steps

Deploying to MCPUsing with Cursor