Claude

The Claude Agent SDK is a local Node.js / Python library, with no remote API to call. Beeps integrates with Claude by triggering a workflow_dispatch GitHub Actions run in your repository; the workflow runs Claude (via anthropics/claude-code-action or the SDK directly), opens a PR with the changes, and beeps polls the workflow run and resolves the PR by branch.

Prerequisites

• A GitHub repository where Claude can run and open PRs.
• A workflow file in that repo (template below).
• An ANTHROPIC_API_KEY stored as a GitHub Actions secret in the repo.
• A fine-grained GitHub PAT (or GitHub App installation token) with these permissions on the target repo:
  • actions: write (to trigger the workflow)
  • actions: read (to poll the workflow run)
  • pull-requests: read (to resolve the PR URL)

Provider-side setup

1. Add the workflow file

Drop this into .github/workflows/claude-beeps.yml. The run-name line is required so beeps can locate the run it triggered:

name: Claude (Beeps)
run-name: "Beeps claude run ${{ inputs.dispatchId }}"

on:
  workflow_dispatch:
    inputs:
      prompt:
        required: true
        type: string
      branch:
        required: true
        type: string
      dispatchId:
        required: true
        type: string
      alertId:
        required: false
        type: string

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: ${{ inputs.prompt }}
      - name: Open PR with changes
        uses: peter-evans/create-pull-request@v6
        with:
          branch: ${{ inputs.branch }}
          title: "Claude: ${{ inputs.alertId }}"
          body: |
            Triggered by beeps alert `${{ inputs.alertId }}`.

            ${{ inputs.prompt }}
          commit-message: "fix: claude response for ${{ inputs.alertId }}"

2. Create the GitHub PAT

Create a fine-grained PAT scoped to the repo with the permissions listed in Prerequisites. Save it; you’ll paste it into beeps as apiKey.

Beeps-side setup

Create the integration with the PAT and repo coordinates:

const claudeIntegration = await client.integration.create({
  name: "Claude - acme/monorepo",
  provider: "claude",
  apiKey: process.env.GITHUB_PAT,
  metadata: {
    githubOwner: "acme",
    githubRepo: "monorepo",
    workflowFileName: "claude-beeps.yml",
    defaultBranch: "main",
    branchPrefix: "claude-beeps",
  },
});

Reference it from a relay rule. Workflow runs typically take a few minutes, so push pollInterval higher than the cloud-API agents:

await client.relay.rules.create(relayId, {
  name: "Claude Auto-Fix",
  ruleType: "agent",
  config: {
    agentType: "claude",
    integrationId: claudeIntegration.id,
    pollInterval: 60000,
    maxPollAttempts: 60,
  },
});

Configuration reference

Integration metadata

Field	Type	Required	Default	Description
githubOwner	string	yes	—	GitHub org or user that owns the repo
githubRepo	string	yes	—	Repo name
workflowFileName	string	yes	—	Workflow filename, e.g. claude-beeps.yml
defaultBranch	string	no	main	Branch to dispatch the workflow against
branchPrefix	string	no	claude-beeps	Prefix for the branch name beeps generates per dispatch

Rule config

The rule needs agentType: "claude" and integrationId. The shared polling and storm-control fields are documented in Relay Rules.

Troubleshooting

Beeps reports “workflow run not found”. Your workflow file is missing the run-name: "Beeps claude run ${{ inputs.dispatchId }}" line. Without it, beeps falls back to “most recent workflow_dispatch run” matching, which is flaky under concurrency.

The PR URL never appears on the alert responder. Beeps resolves the PR by querying GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}, so your workflow needs to open the PR using the inputs.branch value beeps passed in (not a branch the workflow chose itself).