Choosing a Runner

A runner is where your workflow executes. Every recipe is runner-agnostic, so the choice is purely about how and when you want the agent to run. This page compares the options, then gives step-by-step setup for each.

Comparison

All four authenticate to Hud the same way: a HUD_MCP_KEY passed to npx -y hud-mcp@v2. Get the key at app.hud.io → Settings → API keys.

GitHub Actions

A standard .yml workflow, portable to any GitHub repo. Two engine templates are available — Claude Code CLI and Codex CLI. They're identical except for the agent engine and its API key.

Setup

1. Copy three files into your repo, keeping the same paths:
   • .github/workflows/run-agent.yml — the workflow (manual dispatch, with commented-out PR / cron triggers)
   • .github/actions/hud-claude/action.yml — composite action: installs the CLI, configures Hud MCP, runs the prompt
   • .github/actions/hud-claude/prompt.txt — the task prompt
2. Add repo secrets (Settings → Secrets and variables → Actions):
   • HUD_MCP_KEY
   • ANTHROPIC_API_KEY (or Bedrock credentials — see model authentication in the FAQ)
3. Add your prompt. Replace prompt.txt with a recipe from task-recipes/prompts/, or pass an inline prompt via the task_prompt workflow input.
4. Run it manually (Actions → Hud Agent → Run workflow) to verify.

Common tweaks

• Run on PRs. Uncomment the pull_request_target trigger in run-agent.yml. (See running on pull requests safely first.)
• Run on a schedule. Uncomment the schedule: trigger. Note: GitHub cron only fires on the default branch.
• Change the model. Pass model: 'opus' (or sonnet, haiku) on the action call.
• Use Bedrock. Add the AWS credentials step, drop anthropic-api-key, and set CLAUDE_CODE_USE_BEDROCK: '1', AWS_REGION, ANTHROPIC_MODEL.

Multi-file or multi-env prompts

Prompts like the Weekly Report need extra wiring: add the prompt's env vars to the agent step, copy its supporting files (e.g. deep-insights/*.txt) alongside prompt.txt and point PROMPT_DIR at them, add any extra secrets, and uncomment the right trigger. The blast-radius example is a fully worked complex workflow.

gh-aw

gh-aw (GitHub Agentic Workflows) lets you define a workflow as a single markdown file — YAML frontmatter for config, markdown body for the prompt — which compiles down to a normal Actions workflow.

Prerequisites (one-time)

gh extension install github/gh-aw   # install the CLI extension
gh aw init                          # scaffold your repo for agentic workflows

Setup

1. Copy .github/workflows/agent.md into your repo at the same path.
2. Replace the ## Task section of agent.md with your recipe prompt.
3. Compile: gh aw compile — this generates agent.lock.yml.
4. Commit both agent.md and the generated agent.lock.yml.
5. Add repo secrets: HUD_MCP_KEY and ANTHROPIC_API_KEY.
6. Push and test: git push, then gh aw run agent.

How the workflow file is structured

---
# Frontmatter: triggers, permissions, env vars, MCP servers, network rules.
name: my-workflow
engine: claude
on:
  workflow_dispatch:
mcp-servers:
  hud-mcp:
    command: "npx"
    args: ["-y", "hud-mcp@v2"]
    env:
      HUD_MCP_KEY: "${{ secrets.HUD_MCP_KEY }}"
---

## Task
Describe what the agent should do here. (Paste your recipe prompt.)

Common tweaks

• Schedule it. Add a schedule: block to on: (fires only on the default branch).
• Add Slack output. Add SLACK_BOT_TOKEN to env: and add api.slack.com + slack.com to the network.allowed list.
• Open self-heal PRs. Add safe-outputs: { create-pull-request: { draft: true } }.
• Tighten the network allow-list. The default permits defaults, node, github, plus api.hud.io / cdn.hud.io. Remove anything you don't need.

The weekly-report example shows a full multi-phase workflow with Slack output and self-heal.

Cursor

Run a recipe as a Cursor Cloud Agent automation, triggered by a schedule, GitHub event, Slack message, or manually.

Setup

1. Copy AGENTS.md to your repo root and replace its ## Task section with your recipe prompt. (Cursor Cloud reads AGENTS.md automatically.)
2. Create the automation: cursor.com/automations → Create automation → select your repo and branch.
3. Add the Hud MCP server via the MCP dropdown at cursor.com/agents:

{
  "mcpServers": {
    "Hud-MCP": {
      "command": "npx",
      "args": ["-y", "hud-mcp@v2"],
      "env": {
        "HUD_MCP_KEY": "YOUR_HUD_MCP_KEY"
      }
    }
  }
}

4. Pick an output — Open PR, Send Message, or None.
5. Pick a trigger — schedule, GitHub event, Slack message, or manual.
6. Set workspace secrets: HUD_MCP_KEY (plus any others your task needs).

Common tweaks

• Multi-MCP tasks. Add GitHub, Atlassian, Slack, etc. with the same JSON pattern; the agent picks them up by tool name.
• Shell env vars. MCP env is only available to the MCP process — tokens your shell commands need (e.g. GITHUB_PERSONAL_ACCESS_TOKEN) must be set at the automation level.
• Output to PR. Select "Open Pull Request" as the output; Cursor creates the PR from the agent's sandbox changes.

The dead-code-cleanup example is a real Cursor automation using Hud + GitHub + Atlassian MCPs with PR + Jira output.

Claude routine

Two flavors of "Claude with Hud," depending on how you want to invoke it.

Variant A — Skill (on-demand, local)

A Claude Code skill an engineer triggers from a session. Lives in your repo at .claude/skills/<name>/SKILL.md.

1. Copy the skill: cp -r skill/.claude/skills/hud-agent <your-repo>/.claude/skills/ (rename hud-agent to fit your task).
2. Replace the ## Task section with your recipe prompt and update the frontmatter description.
3. Register the Hud MCP locally:
   Bash

   claude mcp add -e HUD_MCP_KEY=$HUD_MCP_KEY --scope user --transport stdio hud -- npx -y hud-mcp@v2

4. Invoke it in a Claude Code session: type /<your-skill-name>.

Best for: incident-time investigations, interactive exploration where a human reviews the verdict, repo-local logic that travels with the codebase.

Variant B — Scheduled remote (continuous, hands-off)

A prompt registered with the scheduled-tasks MCP that runs on Anthropic infrastructure on a cron and posts to a sink (Slack, PagerDuty, GitHub issue, webhook). No files added to your repo.

1. Open scheduled-remote/task.md and replace its ## Task section with your prompt.
2. Register it with mcp__scheduled-tasks__create_scheduled_task at your desired cadence.
3. Wire a delivery step so the verdict goes somewhere visible.

Best for: continuous monitoring that fires without anyone invoking it, fleet-wide coverage, hands-off gates (every deploy, every hour).

📘

You can ship both

The skill is for humans; the scheduled remote is for the machine. Just keep their analysis logic in sync.

The rollback-check example implements both variants of a real production rollback gate.

Pairing a recipe with a runner ("mix & match")

When a matrix cell isn't a worked example, you assemble it yourself:

1. Grab the prompt from task-recipes/prompts/.
2. Grab the runner template from runner-templates/.
3. Drop the prompt into the runner at the path its README expects.
4. Check the prompt's env-var table and wire any required variables into the runner config.