Core Concepts

Understanding the key concepts in Hydra.

Workflows

A workflow is a reusable sequence of AI-assisted development tasks. Workflows are defined using the Hydra Manifest Specification (HMS) and can be:

Private - Only visible to you
Public - Discoverable in the Hydra Marketplace

{
  "name": "My Workflow",
  "intent": "What this workflow accomplishes",
  "steps": [...]
}

Manifests

The Hydra Manifest Specification (HMS) is a JSON-based format for defining workflows. Key features:

Declarative - Define what should happen, not how
Portable - Works across different AI IDEs
Type-safe - Validated against JSON Schema
Composable - Steps can depend on other steps

See the HMS Reference for complete documentation.

Steps

Steps are the building blocks of workflows. Each step has:

Field	Description
`id`	Unique identifier (snake_case)
`name`	Human-readable name
`action`	Type of action to perform
`agent`	Optional agent specialization
`depends_on`	Steps that must complete first
`parameters`	Step-specific configuration

Actions

Available actions:

Action	Description
`analyze_code`	Analyze existing code
`edit_file`	Edit a single file
`edit_files`	Edit multiple files
`generate_code`	Generate new code
`generate_tests`	Generate test files
`execute_command`	Run a shell command
`search_references`	Search for code references
`design_architecture`	Create architectural designs
`review_and_commit`	Review and commit changes

Adapters

Adapters translate HMS manifests into IDE-specific instructions. Hydra supports:

Claude Code Adapter

Uses the sub-agent spawning pattern:

Each step can spawn a specialized sub-agent
Supports parallel execution
Best for complex, multi-phase workflows

Cursor Adapter

Uses the Composer pattern:

Optimized for Cursor's multi-file editing
Inline diff support
Best for interactive editing workflows

Codex Adapter

Uses the function calling pattern:

Maps steps to function calls
Sequential execution
Best for automated pipelines

Deployments

A deployment packages one or more workflows for use in your IDE:

Select workflows to include
Choose target adapters (Claude, Cursor, Codex)
Get an MCP endpoint URL
Connect your IDE

Workflow → Deployment → MCP Endpoint → IDE

MCP (Model Context Protocol)

MCP (Model Context Protocol) is an open standard created by Anthropic that allows AI assistants to connect to external tools, data sources, and capabilities.

Why MCP?

Think of MCP as a "plugin system" for AI assistants. Just like web browsers have extensions, AI tools like Claude Code and Cursor can connect to MCP servers to gain new capabilities.

How Hydra Uses MCP

When you connect your IDE to Hydra:

Your IDE → connects to → Hydra MCP Server → serves → Your Workflows

You configure your IDE with your Hydra MCP endpoint URL
Hydra serves your workflows as tools the AI can use
Your IDE's AI can now list, understand, and execute your workflows

MCP Endpoint vs API Key

Method	Used By	When to Use
MCP URL	Claude Code, Cursor	Real-time IDE integration
API Key	Codex CLI, scripts	Programmatic access

Your MCP endpoint URL looks like: https://API_BASE_URL/mcp/YOUR_DEPLOYMENT_ID

Each deployment has its own unique MCP endpoint. You'll find the exact URL in your deployment details after creating one.

Learn more: MCP Documentation (opens in a new tab) | Anthropic MCP Guide (opens in a new tab)

Marketplace

The Hydra Marketplace is where you can:

Discover public workflows created by the community
Fork workflows to customize for your needs
Subscribe to workflows to get automatic updates
Publish your own workflows for others to use

Forking vs Subscribing

Feature	Fork	Subscribe
Get your own copy	✅	❌
Customize freely	✅	❌
Automatic updates	❌	✅
Version pinning	N/A	✅

Version Pinning

When subscribing to a workflow, you can control updates:

Pin	Behavior
`latest`	Always use the latest version
`^1.0`	Allow minor updates (1.x)
`~1.2`	Allow patch updates (1.2.x)
`1.2.3`	Exact version only

Next Steps

Follow the Quick Start tutorial
Read the HMS Reference
Browse IDE Integration Guides

Quick Start IDE Setup