Quick Start Guide

Build your first Hephaestus workflow in 10 minutes.

What You'll Build

A simple 3-phase bug fixing workflow:

Phase 1: Reproduce the bug
Phase 2: Find the root cause
Phase 3: Implement and verify the fix

Prerequisites

Claude Code, OpenCode, Droid, or Codex installed (CLI AI tool that agents run in)
tmux installed (terminal multiplexer for agent isolation)
Git (for worktree isolation - your project directory must be a git repo)
Python 3.10+
Node.js and npm (for the frontend UI)
Docker (for running Qdrant vector store)
API Keys: OpenAI, OpenRouter (or Anthropic - see LLM Configuration below)

Validate Your Setup (macOS)

Before proceeding with configuration, we recommend validating that everything is installed correctly:

python check_setup_macos.py

What this script checks:

✅ CLI Tools - tmux, git, docker, node, npm, Claude Code, OpenCode, Python 3.10+
✅ API Keys - .env file and required keys (OPENAI_API_KEY, OPENROUTER_API_KEY, etc.)
✅ MCP Servers - Claude MCP accessible, Hephaestus and Qdrant MCP servers configured
✅ Configuration - hephaestus_config.yaml exists and has required fields
✅ Working Directory - Project directory exists, is git repo, has commits, has PRD.md
✅ Services - Docker daemon running, Qdrant accessible on port 6333
✅ Dependencies - Python packages and frontend node_modules installed

Example output:

🔍 Hephaestus Setup Validation

Checking CLI Tools...
Checking API Keys...
Checking MCP Servers...
Checking Configuration...
Checking Working Directory...
Checking Services...
Checking Dependencies...

============================================================
SETUP VALIDATION SUMMARY
============================================================

Cli Tools:
  ✓ tmux
  ✓ git
  ✓ docker
  ✓ node
  ✓ npm
  ✓ Claude Code
  ✓ OpenCode (optional)
  ✓ Python 3.10+

Api Keys:
  ✓ .env file exists
  ✓ OPENAI_API_KEY
  ✓ OPENROUTER_API_KEY (optional)
  ✓ ANTHROPIC_API_KEY (optional)

[... more categories ...]

============================================================
✓ ALL CHECKS PASSED
Passed: 31/31 (100.0%)
============================================================

The script provides a color-coded report:

Green ✓ - Item is set up correctly
Red ✗ - Item needs attention
Overall status - 100% = all pass, 80%+ = mostly ready, <80% = setup incomplete

If any checks fail, proceed to the relevant setup sections below to fix them.

LLM Configuration

Before running workflows, configure which LLMs to use in hephaestus_config.yaml.

Recommended Setup (Default)

The pre-configured hephaestus_config.yaml uses:

OpenAI for embeddings (text-embedding-3-large)
OpenRouter with Cerebras provider for all tasks (gpt-oss:120b)

This is the recommended setup - OpenRouter with Cerebras is extremely fast (1000+ tokens/sec), cost-effective, and performs well on most tasks.

llm:
  embedding_model: "text-embedding-3-large"
  default_provider: "openrouter"
  default_model: "openai/gpt-oss-120b"
  default_openrouter_provider: "cerebras"  # Cerebras infrastructure for speed

Required API Keys:

# .env file
OPENAI_API_KEY=sk-...        # For embeddings
OPENROUTER_API_KEY=sk-...    # For OpenRouter (Cerebras provider)

Alternative: OpenAI Only

If you prefer a single provider:

llm:
  default_provider: "openai"
  default_model: "gpt-5"      # Or "gpt-5-mini" for cheaper option

Models we recommend:

gpt-oss:120b (OpenRouter with Cerebras) - Best performance/cost, extremely fast
gpt-5 (OpenAI) - Strong reasoning, higher cost
gpt-5-mini (OpenAI) - Faster, cheaper alternative

Alternative: Azure OpenAI (For Business Users)

For enterprises with Azure subscriptions:

llm:
  embedding_provider: "azure_openai"
  providers:
    azure_openai:
      api_key_env: "AZURE_OPENAI_API_KEY"
      base_url: "https://YOUR-RESOURCE.openai.azure.com"
      api_version: "2024-02-01"
  model_assignments:
    task_enrichment:
      provider: "azure_openai"
      model: "gpt-4"  # Your deployment name from Azure portal

Required API Keys:

# .env file
AZURE_OPENAI_API_KEY=your-azure-key

Important: Use deployment names (configured in Azure portal), not model names! See examples/azure_config_example.yaml for complete configuration.

Alternative: Google AI Studio (Gemini)

For Google Gemini models with simple API key setup:

llm:
  embedding_provider: "google_ai"
  providers:
    google_ai:
      api_key_env: "GOOGLE_API_KEY"
  model_assignments:
    task_enrichment:
      provider: "google_ai"
      model: "gemini-2.5-flash"

Required API Keys:

# .env file
GOOGLE_API_KEY=your-google-key

Get your API key from https://ai.google.dev/. See examples/google_config_example.yaml for complete configuration.

Agent CLI Configuration

Agents run inside a CLI AI tool. Choose which CLI tool to use:

CLI Tool Options

Claude Code (Default):

agents:
  default_cli_tool: "claude"
  cli_model: "sonnet"  # Options: "sonnet", "opus", "haiku", "GLM-4.6"

Uses your Anthropic subscription through Claude Code. Supports Claude models and GLM-4.6 for cheaper alternative.

Using GLM-4.6 (cheaper model through Claude Code):

agents:
  default_cli_tool: "claude"
  cli_model: "GLM-4.6"
  glm_api_token_env: "GLM_API_TOKEN"

Then set your GLM API token:

# .env file
GLM_API_TOKEN=your-glm-token

GLM-4.6 is significantly cheaper than Claude models while maintaining good performance.

OpenCode (Open-Source Alternative):

agents:
  default_cli_tool: "opencode"
  cli_model: "anthropic/claude-sonnet-4"  # Uses provider/model format

OpenCode benefits:

Supports 75+ LLM providers (Anthropic, OpenAI, OpenRouter, etc.)
Open-source and free
Uses provider/model format (e.g., anthropic/claude-sonnet-4, openai/gpt-4)

Install OpenCode:

npm install -g @opencodehq/opencode
# or
pip install opencode

MCP Server Setup

Before running workflows, you need to configure the MCP servers that agents use to interact with Hephaestus and Qdrant.

1. Qdrant MCP Server

This gives agents access to the vector store (memory/RAG system):

claude mcp add -s user qdrant python /path/to/qdrant_mcp_openai.py \
  -e QDRANT_URL=http://localhost:6333 \
  -e COLLECTION_NAME=hephaestus_agent_memories \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e EMBEDDING_MODEL=text-embedding-3-large

Replace /path/to/qdrant_mcp_openai.py with the actual path to the script in your Hephaestus installation.

2. Hephaestus MCP Server

This gives agents access to task management, phase information, and workflow coordination:

claude mcp add -s user hephaestus python /path/to/claude_mcp_client.py

Replace /path/to/claude_mcp_client.py with the actual path to the script in your Hephaestus installation.

What these MCP servers provide:

Qdrant MCP gives agents:

qdrant_find - Search for relevant memories using semantic search
qdrant_store - Save discoveries and learnings

Hephaestus MCP gives agents:

create_task - Spawn new tasks for any phase
get_tasks - Query task status and information
update_task_status - Mark tasks as done/failed
save_memory - Store learnings in the knowledge base
get_agent_status - Check other agents' status
And more...

These MCP servers are configured once per user and will be available to all agents running in Claude Code.

Working Directory Setup

Hephaestus needs to know where your project is located. This is the directory where agents will read files, write code, and make changes.

1. Create or Choose Your Project Directory

# Create a new project directory
mkdir -p ~/my_project
cd ~/my_project

# Initialize as a git repository (REQUIRED)
git init

Important: The working directory must be a git repository. Hephaestus uses Git worktrees to isolate agent changes and prevent conflicts.

2. Configure the Path in `hephaestus_config.yaml`

Edit the paths in hephaestus_config.yaml:

# Paths Configuration
paths:
  database: "./hephaestus.db"
  worktree_base: "/tmp/hephaestus_worktrees"
  project_root: "/Users/yourname/my_project"  # Change this to your project path

# Git Configuration
git:
  main_repo_path: "/Users/yourname/my_project"  # Change this to match project_root
  worktree_branch_prefix: "agent-"
  auto_commit: true
  conflict_resolution: "newest_file_wins"

Both paths must point to the same directory and it must be a git repository.

3. Add Your PRD (Product Requirements Document)

Create a PRD.md file in your project directory:

cd ~/my_project
touch PRD.md
# Edit PRD.md with your project requirements

Hephaestus will automatically find PRD.md in the project root - you don't need to specify the path when running workflows.

Step 1: Define Your Phases

Create my_workflow/phases.py:

from src.sdk.models import Phase

PHASE_1_REPRODUCTION = Phase(
    id=1,
    name="bug_reproduction",
    description="Reproduce the reported bug and capture evidence",
    done_definitions=[
        "Bug reproduced successfully",
        "Reproduction steps documented",
        "Error logs captured",
        "Phase 2 investigation task created",
        "Task marked as done"
    ],
    working_directory=".",
    additional_notes="""
    🎯 YOUR MISSION: Confirm the bug exists

    STEP 1: Read the bug report in your task description
    STEP 2: Follow the reproduction steps
    STEP 3: Capture error messages and logs
    STEP 4: If bug confirmed: Create Phase 2 task
    STEP 5: Mark your task as done

    ✅ GOOD: "Bug reproduced. Error: 'Cannot read property of undefined' at login.js:47"
    ❌ BAD: "It crashes sometimes"
    """
)

PHASE_2_INVESTIGATION = Phase(
    id=2,
    name="root_cause_analysis",
    description="Find the root cause of the bug",
    done_definitions=[
        "Root cause identified",
        "Affected code located",
        "Fix approach proposed",
        "Phase 3 implementation task created",
        "Task marked as done"
    ],
    working_directory=".",
    additional_notes="""
    🎯 YOUR MISSION: Find WHY the bug happens

    STEP 1: Review reproduction evidence from Phase 1
    STEP 2: Trace through the code
    STEP 3: Identify the faulty code
    STEP 4: Propose a fix
    STEP 5: Create Phase 3 task with fix details
    STEP 6: Mark done
    """
)

PHASE_3_FIX = Phase(
    id=3,
    name="fix_implementation",
    description="Implement the bug fix and verify it works",
    done_definitions=[
        "Bug fix implemented",
        "Tests added to prevent regression",
        "All tests pass",
        "Bug cannot be reproduced anymore",
        "Task marked as done"
    ],
    working_directory=".",
    additional_notes="""
    🎯 YOUR MISSION: Apply the fix and verify

    STEP 1: Implement the proposed fix
    STEP 2: Add regression test
    STEP 3: Run all tests
    STEP 4: Verify bug is fixed
    STEP 5: Mark done
    """
)

BUG_FIX_PHASES = [
    PHASE_1_REPRODUCTION,
    PHASE_2_INVESTIGATION,
    PHASE_3_FIX
]

Step 2: Configure the Workflow

Create my_workflow/config.py:

from src.sdk.models import WorkflowConfig

BUG_FIX_CONFIG = WorkflowConfig(
    has_result=True,
    result_criteria="Bug is fixed and verified: cannot be reproduced, tests pass",
    on_result_found="stop_all"
)

Step 3: Create the Runner Script

Create run_bug_fix.py:

#!/usr/bin/env python3
import os
import sys
from pathlib import Path
from dotenv import load_dotenv

# Add project to path
sys.path.insert(0, str(Path(__file__).parent))

# Import phases
from my_workflow.phases import BUG_FIX_PHASES
from my_workflow.config import BUG_FIX_CONFIG

from src.sdk import HephaestusSDK

# Load environment
load_dotenv()

def main():
    # Initialize SDK
    sdk = HephaestusSDK(
        phases=BUG_FIX_PHASES,
        workflow_config=BUG_FIX_CONFIG,
        database_path="./hephaestus.db",
        qdrant_url="http://localhost:6333",
        llm_provider=os.getenv("LLM_PROVIDER", "openai"),
        working_directory=".",
        mcp_port=8000,
        monitoring_interval=60
    )

    # Start services
    print("[Hephaestus] Starting services...")
    sdk.start()

    print("[Hephaestus] Loaded phases:")
    for phase_id, phase in sorted(sdk.phases_map.items()):
        print(f"  - Phase {phase_id}: {phase.name}")

    # Create initial task
    print("\n[Task] Creating Phase 1 bug reproduction task...")
    task_id = sdk.create_task(
        description="""
        Phase 1: Reproduce Bug - "Login fails with special characters"

        Bug Report:
        - User enters password with @ symbol
        - Login button becomes unresponsive
        - Error in console: "Invalid character in auth string"

        Reproduce this bug and capture evidence.
        """,
        phase_id=1,
        priority="high",
        agent_id="main-session-agent"
    )
    print(f"[Task] Created task: {task_id}")

    # Keep running
    print("\n[Hephaestus] Workflow running. Press Ctrl+C to stop.\n")
    try:
        while True:
            import time
            time.sleep(10)
    except KeyboardInterrupt:
        print("\n[Hephaestus] Shutting down...")
        sdk.shutdown(graceful=True, timeout=10)
        print("[Hephaestus] Shutdown complete")

if __name__ == "__main__":
    main()

Step 4: Run the Workflow

Before running, ensure you've completed the setup:

✅ Working directory configured in hephaestus_config.yaml
✅ Directory initialized as git repository (git init)
✅ MCP servers configured (claude mcp list to verify)
✅ API keys set in .env file

Start the required services:

# Terminal 1: Start Qdrant (vector store)
docker run -d -p 6333:6333 qdrant/qdrant

# Terminal 2: Start the frontend UI
cd frontend
npm install  # First time only
npm run dev

# Terminal 3: Run your workflow
python run_hephaestus_dev.py --path /tmp/test_prd --drop-db

Note: The SDK automatically starts the Hephaestus server - you don't need to run run_server.py separately!

View the workflow in action: Open your browser to http://localhost:3000. You'll see:

Phases Overview - Task counts and active agents per phase
Task List - Real-time updates as agents work
Workflow Graph - Visual representation of task creation and dependencies
Trajectory Analysis - Agent alignment scores and Guardian interventions

Using Example Workflows

Quick Start: Run the Example

Instead of building your own workflow from scratch, use our pre-built example with two workflows:

⚠️ Important: Initial Claude CLI Setup

Before running the Hephaestus application for the first time if you haven't used Claude Code before, you must initialize the Claude Code CLI tool and accept the liability prompt. If you skip this step, your agents will get stuck and the workflow will not progress.

Open your terminal and run the following command:

claude --model sonnet --dangerously-skip-permissions

The tool will launch and display a legal/liability warning. Read and accept this prompt to allow Claude Code to run.
Once accepted, you can exit the tool, and the Hephaestus agents will be able to launch it without being blocked.

All-in-One Runner (simplest approach):

# Terminal 1: Start Qdrant (if not already running)
docker run -d -p 6333:6333 qdrant/qdrant

# Terminal 2: Run the complete example
python run_hephaestus_dev.py

The run_hephaestus_dev.py script will:

Check and setup sub-agents in ~/.claude/agents/
Prompt for project path (creates directory automatically)
Copy PRD.md and .gitignore to your project
Initialize git repository with initial commit
Update config with your project path
Start Hephaestus with two workflow definitions registered:
- PRD to Software Builder - Build software from requirements
- Bug Fix - Analyze, fix, and verify bugs

Launching Workflows from UI

Once Hephaestus is running, open http://localhost:3000 and navigate to Workflow Executions:

Click "Launch Workflow"
Select a workflow (e.g., "PRD to Software Builder")
Fill in the form:
- Project Name: "Personal Task Manager"
- Project Type: "Web Application"
- PRD Content: (paste your full PRD here)
- Technology Preferences: (optional)
Review the preview
Click "Launch"

The workflow starts automatically with your inputs!

Available workflows:

Workflow	Description	Form Fields
PRD to Software Builder	Build software from a PRD	Project name, project type, PRD content, tech preferences
Bug Fix	Fix and verify bugs	Bug description, type, severity, reproduction steps

What you get:

A complete Personal Task Manager app with:
- FastAPI backend + React frontend
- SQLite database
- Task CRUD operations (create, view, edit, delete)
- Proper project structure with separate frontend/ and backend/ directories

The workflow will:

Parse the PRD and identify components
Create Kanban tickets for each component
Design each component in parallel (Phase 2)
Implement each component (Phase 3)
Test and validate (Phase 4)
Submit final result when complete

Track progress at:

Frontend UI: http://localhost:3000/
Workflow Executions: http://localhost:3000/workflow-executions
Kanban Board: http://localhost:3000/tickets

Advanced: Build Your Own Workflow

Want to create custom workflows? Here's the pattern:

from src.sdk import HephaestusSDK
from src.sdk.models import (
    Phase, WorkflowConfig, LaunchTemplate,
    LaunchParameter, WorkflowDefinition
)

# 1. Define phases
my_phases = [
    Phase(id=1, name="analyze", description="Analyze the problem", ...),
    Phase(id=2, name="solve", description="Implement solution", ...),
    Phase(id=3, name="verify", description="Verify it works", ...),
]

# 2. Configure result handling
my_config = WorkflowConfig(
    has_result=True,
    result_criteria="Problem is solved",
    on_result_found="complete"
)

# 3. Create launch template for UI
my_template = LaunchTemplate(
    parameters=[
        LaunchParameter(name="problem", label="Problem", type="textarea", required=True),
        LaunchParameter(name="priority", label="Priority", type="dropdown",
                       options=["Low", "Medium", "High"], default="Medium"),
    ],
    phase_1_task_prompt="Analyze this problem: {problem}\nPriority: {priority}"
)

# 4. Bundle into WorkflowDefinition
my_workflow = WorkflowDefinition(
    id="problem-solver",
    name="Problem Solver",
    description="Analyze and solve problems",
    phases=my_phases,
    config=my_config,
    launch_template=my_template,
)

# 5. Register with SDK
sdk = HephaestusSDK(
    workflow_definitions=[my_workflow],
    working_directory="/path/to/project",
    main_repo_path="/path/to/project",
)

sdk.start()
# Users can now launch from http://localhost:3000

Note: Make sure you have:

Set up your working directory path in hephaestus_config.yaml
Initialized the directory as a git repository (git init)

See Defining Phases and Launch Templates for complete guides.

Example workflows to study:

example_workflows/prd_to_software/phases.py - PRD to software workflow
example_workflows/bug_fix/phases.py - Bug fixing workflow
run_hephaestus_dev.py - Multi-workflow setup

What Happens

┌─────────────────────────────────────────────────────────────┐
│ Phase 1 Agent (Reproduction)                                │
│ - Reads bug report                                          │
│ - Attempts to reproduce                                     │
│ - Captures error: "Invalid character at auth.js:47"        │
│ - Creates Phase 2 investigation task                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2 Agent (Investigation)                               │
│ - Reviews reproduction evidence                             │
│ - Traces through auth.js                                    │
│ - Finds issue: password not URL-encoded                     │
│ - Creates Phase 3 fix task                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3 Agent (Fix)                                         │
│ - Implements fix: encodeURIComponent(password)             │
│ - Adds regression test                                      │
│ - Runs tests: ALL PASS ✓                                   │
│ - Verifies bug is fixed                                     │
└─────────────────────────────────────────────────────────────┘

Throughout this process:

Guardian monitors every 60 seconds
Steers agents if they drift from phase instructions
Validates that each phase follows its mandatory steps

Monitoring Progress

View Logs

tail -f logs/backend.log   # Server logs
tail -f logs/monitor.log   # Guardian logs

Check Task Status

# In Python console or script
from src.sdk import HephaestusSDK
sdk = HephaestusSDK(...)
tasks = sdk.get_tasks(status="in_progress")
for task in tasks:
    print(f"{task.id}: {task.description[:50]}... - {task.status}")

View Agent Status

# Check active agents
curl http://localhost:8000/api/agents/status

Next Steps

Now that you've built a basic workflow, try:

Add Ticket Tracking: Enable Kanban board coordination

config = WorkflowConfig(
    enable_tickets=True,
    board_config={...}
)

Add More Phases: Extend to 4-5 phases for complex workflows

Enable Validation: Add automated validation criteria

phase = Phase(
    ...,
    validation={
        "enabled": True,
        "criteria": [...]
    }
)

Study Examples: Explore example_workflows/ for real-world workflow patterns
Learn Best Practices: Read Best Practices Guide for workflow design patterns

Troubleshooting

Problem: Agents not spawning

Check logs: tail -f logs/backend.log
Verify Qdrant running: curl http://localhost:6333/health
Check API key in .env

Problem: Guardian not steering

Verify monitoring interval in config
Check logs/monitor.log for Guardian analysis
Ensure phase instructions are clear and specific

Problem: Tasks stuck

Check agent tmux sessions: tmux ls
View agent output: tmux attach -t agent-xxx
Check for errors in logs/backend.log

Problem: LLM errors

Verify API keys in .env file
Check hephaestus_config.yaml has correct provider/model configuration
Review logs for authentication errors

Problem: Agents can't access MCP tools

Verify MCP servers are configured: claude mcp list
Check that both hephaestus and qdrant MCP servers are listed
Re-run the MCP server setup commands if missing
Restart Claude Code after adding MCP servers

Problem: Git worktree errors

Ensure your working directory is initialized as a git repository: git init
Verify paths in hephaestus_config.yaml point to the correct directory
Check that project_root and main_repo_path match
The directory must have at least one commit: git commit --allow-empty -m "Initial commit"

Congratulations! You've built your first Hephaestus workflow.

Next: Learn about Guardian Monitoring to see how Guardian keeps workflows on track.

What You'll Build​

Prerequisites​

Validate Your Setup (macOS)​

LLM Configuration​

Recommended Setup (Default)​

Alternative: OpenAI Only​

Alternative: Azure OpenAI (For Business Users)​

Alternative: Google AI Studio (Gemini)​

Agent CLI Configuration​

CLI Tool Options​

MCP Server Setup​

1. Qdrant MCP Server​

2. Hephaestus MCP Server​

Working Directory Setup​

1. Create or Choose Your Project Directory​

2. Configure the Path in hephaestus_config.yaml​

3. Add Your PRD (Product Requirements Document)​

Step 1: Define Your Phases​

Step 2: Configure the Workflow​

Step 3: Create the Runner Script​

Step 4: Run the Workflow​

Using Example Workflows​

Quick Start: Run the Example​

⚠️ Important: Initial Claude CLI Setup​

Launching Workflows from UI​

Advanced: Build Your Own Workflow​

What Happens​

Monitoring Progress​

View Logs​

Check Task Status​

View Agent Status​

Next Steps​

Troubleshooting​

What You'll Build

Prerequisites

Validate Your Setup (macOS)

LLM Configuration

Recommended Setup (Default)

Alternative: OpenAI Only

Alternative: Azure OpenAI (For Business Users)

Alternative: Google AI Studio (Gemini)

Agent CLI Configuration

CLI Tool Options

MCP Server Setup

1. Qdrant MCP Server

2. Hephaestus MCP Server

Working Directory Setup

1. Create or Choose Your Project Directory

2. Configure the Path in `hephaestus_config.yaml`

3. Add Your PRD (Product Requirements Document)

Step 1: Define Your Phases

Step 2: Configure the Workflow

Step 3: Create the Runner Script

Step 4: Run the Workflow

Using Example Workflows

Quick Start: Run the Example

⚠️ Important: Initial Claude CLI Setup

Launching Workflows from UI

Advanced: Build Your Own Workflow

What Happens

Monitoring Progress

View Logs

Check Task Status

View Agent Status

Next Steps

Troubleshooting