---
updatedAt: 2026-09-30T10:53:38.000Z
agentTools:
  projectIndex: https://docs.hud.io/llms.txt
---

# Choosing a Runner

Compare the four runners — GitHub Actions, gh-aw, Cursor, and Claude routines — and follow step-by-step setup for each.

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.

<br />

***

## Comparison

| Runner             | Integration             | What you do                                                    | Best for                                                          |
| ------------------ | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| **GitHub Actions** | Copy files              | Copy `.github/` files to your repo, set secrets                | PR-triggered checks, cron jobs, teams already on Actions          |
| **gh-aw**          | Copy files + compile    | Copy a single `.md` workflow, run `gh aw compile`, set secrets | The same triggers as Actions, in a compact markdown + YAML format |
| **Cursor**         | Copy + UI               | Copy `AGENTS.md`, create an automation in the Cursor dashboard | Teams on Cursor; manual or scheduled triggers, PR/Slack output    |
| **Claude routine** | Copy file *or* register | Copy a skill file, **or** register a scheduled task via MCP    | On-demand (skill) or continuous, hands-off cron monitoring        |

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](https://www.app.hud.io/settings/api-keys?environment=production).

<br />

***

## GitHub Actions

A standard `.yml` workflow, portable to any GitHub repo. Two engine templates are available — [Claude Code CLI](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/runner-templates/github-actions-claude) and [Codex CLI](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/runner-templates/github-actions-codex). 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](https://docs.hud.io/docs/agentic-workflows-faq))
3. **Add your prompt.** Replace `prompt.txt` with a recipe from [`task-recipes/prompts/`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/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](https://docs.hud.io/docs/agentic-workflows-faq) 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](https://docs.hud.io/docs/agentic-workflows-recipes) 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](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/full-examples/blast-radius-github-actions) is a fully worked complex workflow.

<br />

***

## gh-aw

[gh-aw](https://github.github.com/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)

```bash
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`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/runner-templates/gh-aw) 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

```markdown
---
# 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](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/full-examples/weekly-report-gh-aw) shows a full multi-phase workflow with Slack output and self-heal.

<br />

***

## Cursor

Run a recipe as a [Cursor Cloud Agent](https://cursor.com/automations) automation, triggered by a schedule, GitHub event, Slack message, or manually.

### Setup

1. **Copy** [`AGENTS.md`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/runner-templates/cursor) 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](https://cursor.com/automations) → Create automation → select your repo and branch.
3. **Add the Hud MCP server** via the MCP dropdown at [cursor.com/agents](https://cursor.com/agents):

```json
{
  "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](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/full-examples/dead-code-cleanup-cursor) is a real Cursor automation using Hud + GitHub + Atlassian MCPs with PR + Jira output.

<br />

***

## 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](https://docs.hud.io/docs/hud-mcp-server) 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`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/runner-templates/claude-routine) 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](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/full-examples/rollback-check-claude-routine) implements both variants of a real production rollback gate.

<br />

***

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

When a [matrix](https://docs.hud.io/docs/agentic-workflows#use-case--runner-matrix) cell isn't a worked example, you assemble it yourself:

1. Grab the **prompt** from [`task-recipes/prompts/`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/task-recipes/prompts).
2. Grab the **runner template** from [`runner-templates/`](https://github.com/code-hud/hud-agentic-workflows-recipes/tree/main/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.

<br />

<HTMLBlock>{`
<b>Need Help?</b>
<a href="https://www.app.hud.io/?support_chat=true" target="_blank">Chat with our support team</a>
or email us at
<a href="mailto:support@hud.io" target="_blank">support@hud.io</a>.
`}</HTMLBlock>