Getting Started
15-Minute Tutorial

End-to-End Tutorial

Learn Hydra by building and deploying your first workflow in 15 minutes.

What You'll Build

By the end of this tutorial, you will have:

  1. Created a Hydra account
  2. Forked a workflow from the Marketplace
  3. Connected it to your IDE (Claude Code, Cursor, or Codex CLI)
  4. Executed the workflow on real code
  5. Created and published your own workflow

Prerequisites

⚠️

New to these tools? Read the Prerequisites Guide first for detailed setup instructions and explanations of what each tool does.

Part 1: Getting Started with Hydra

Create Your Account

  1. Go to hydra.opiusai.com (opens in a new tab)
  2. Click "Get Started" in the top right
  3. Sign up with GitHub (recommended) or email
  4. Complete your profile

GitHub sign-up gives you access to import repositories directly into workflows.

Explore the Dashboard

After signing in, you'll land on your Dashboard. Here you can see:

  • My Workflows - Workflows you've created or forked
  • My Subscriptions - Workflows you're subscribed to for updates

New accounts start with an empty dashboard. Let's add some workflows!

Browse the Marketplace

  1. Click "Marketplace" in the navigation

  2. You'll see community-published workflows organized by category:

    • Development - Bug fixes, refactoring
    • Testing - Test generation, coverage
    • DevOps - CI/CD, deployment
    • Documentation - API docs, READMEs

  3. Use the search bar to find workflows, or filter by category

Part 2: Fork Your First Workflow

Recommended for Beginners: The Bug Fix Workflow is the best starting point because it:

  • Has a simple 3-step structure (analyze → fix → test)
  • Works on any codebase
  • Shows clear before/after results
  • Teaches the core workflow pattern

Find a Workflow

For this tutorial, we'll use the "Bug Fix Workflow":

  1. In the Marketplace, search for "Bug Fix"
  2. Click on the "Bug Fix Workflow" card
  3. Review the workflow details:
    • Intent - What the workflow accomplishes
    • Steps - The sequence of actions
    • Manifest - The underlying JSON specification

Fork the Workflow

  1. Click the "Fork" button
  2. Give your fork a name (e.g., "My Bug Fix Workflow")
  3. Click "Create Fork"

Your fork is now in My Workflows on your dashboard!

Forking creates your own copy that you can customize. The original workflow remains unchanged.

Review the Manifest

Click on your forked workflow to open the Visual Builder. The manifest looks like this:

{
  "$schema": "https://hydra.opiusai.com/schemas/workflow/v1.0.json",
  "manifest_version": "1.0",
  "name": "Bug Fix Workflow",
  "intent": "Identify, analyze, and fix a reported bug with tests",
  "steps": [
    {
      "id": "analyze",
      "name": "Analyze the bug",
      "action": "analyze_code",
      "agent": "bug_analyzer",
      "parameters": {
        "focus": "root cause identification"
      }
    },
    {
      "id": "fix",
      "name": "Implement the fix",
      "action": "edit_file",
      "depends_on": ["analyze"]
    },
    {
      "id": "test",
      "name": "Write tests",
      "action": "generate_tests",
      "depends_on": ["fix"]
    }
  ]
}

Each step has:

  • id - Unique identifier
  • name - Human-readable name
  • action - What the AI should do
  • depends_on - Steps that must complete first

Part 3: Connect Your IDE

Now let's connect Hydra to your IDE using the Model Context Protocol (MCP).

What is MCP? MCP is an open protocol that lets AI assistants connect to external tools. Think of it like a "plugin system" for AI - it allows Claude Code, Cursor, and other tools to access Hydra's workflows. Your IDE connects to Hydra's MCP server, which serves your workflow definitions.

Claude Code Setup

Step 1: Deploy your workflow

  1. In the Hydra Dashboard, open your forked workflow
  2. Click Deploy
  3. Select Claude Code as the target adapter
  4. Copy the MCP endpoint URL from the deployment details

Step 2: Configure Claude Code

Create or edit ~/.claude/settings.json:

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

Replace YOUR_MCP_ENDPOINT_URL with the endpoint from your deployment.

Step 3: Restart Claude Code

Close and reopen Claude Code. You should see "Hydra" listed in your available tools.

Step 4: Verify connection

In Claude Code, type:

List my Hydra workflows

You should see your forked Bug Fix Workflow!

Verification Checklist

If your setup is working correctly, you should be able to:

  • List your Hydra workflows from your IDE
  • See the "Bug Fix Workflow" you forked earlier

If you don't see your workflows, check the Troubleshooting Guide.

Part 4: Execute Your Workflow

Open Your Project

Navigate to a project with a bug you want to fix (or create a simple test file):

// buggy.js - A file with an obvious bug
function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i <= items.length; i++) {  // Bug: <= should be <
    total += items[i].price;
  }
  return total;
}

Run the Workflow

In Claude Code, describe the bug:

Run my Bug Fix Workflow on buggy.js.
The calculateTotal function throws an error when processing arrays.

Claude will:

  1. Analyze - Read the file and identify the off-by-one error
  2. Fix - Suggest changing <= to <
  3. Test - Generate a test file to verify the fix

Review the Results

The workflow will:

  1. Output an analysis explaining the bug
  2. Show the proposed fix (inline or as a diff)
  3. Generate test code to prevent regression

Congratulations! You've executed your first Hydra workflow.

Part 5: Create Your Own Workflow

Now let's create a custom workflow from scratch.

Open the Builder

  1. Go to your Dashboard
  2. Click "New Workflow"
  3. Choose "Start from Scratch"

Define the Workflow

Let's create a simple code documentation workflow:

  1. Name: "Document Code"
  2. Intent: "Add JSDoc comments to functions and classes"

Add Steps

Click "Add Step" for each:

Step 1: Analyze

  • ID: scan
  • Name: Scan for undocumented code
  • Action: analyze_code
  • Parameters: { "focus": "functions and classes without documentation" }

Step 2: Document

  • ID: document
  • Name: Add documentation
  • Action: edit_files
  • Depends On: scan
  • Parameters: { "focus": "JSDoc/docstring format" }

Save and Test

  1. Click "Save"
  2. Click "Test" to try it on sample code
  3. When satisfied, click "Publish" to share on the Marketplace

Next Steps

You've learned the fundamentals of Hydra! Here's where to go next:

Core ConceptsCreating WorkflowsHMS ReferenceExamples

Troubleshooting

"Workflow not found" error

  • Verify you're signed in to the correct Hydra account
  • Check your MCP endpoint URL is correct
  • Restart your IDE after configuration changes

IDE not connecting

  • Ensure your firewall allows connections to *.execute-api.us-west-2.amazonaws.com
  • Check that MCP is enabled in your IDE settings
  • Verify your MCP endpoint URL is correct (from Dashboard → Deployments)

Workflow steps not executing in order

  • Check depends_on arrays in your manifest
  • Ensure no circular dependencies exist
  • Review the execution plan in the Builder

For more help, see the Troubleshooting Guide or contact us at support@opiusai.com.

PrerequisitesQuick Start