Feature Request: Extend Hooks System to Support GitHub Webhook Events

Title: Feature Request: Extend Hooks System to Support GitHub Webhook Events

Labels: feature-request, enhancement, hooks, github, automation

Problem Statement

The hooks system (PreToolUse, PostToolUse, etc.) is an exceptionally powerful and elegant feature for creating deterministic, script-based customizations for the local claude-code agent lifecycle. It's lightweight, configured in settings.json, and aligns perfectly with the tool's scriptable, Unix-style philosophy.

For repository-level automation, claude-code offers the Claude Code GitHub Actions. This is a fantastic solution for complex, agentic workflows, typically triggered by a @claude mention.

However, a functional gap exists between these two systems. There is currently no "Claude-native" way to trigger lightweight, deterministic, script-based automations in response to raw GitHub webhook events (e.g., issues.opened, pull_request.synchronize). Developers who want to perform a simple action—like automatically labeling an issue or running a quick linter script—must either set up a full GitHub Actions workflow or build a custom solution. This adds friction and moves the automation logic outside the unified Claude Code configuration ecosystem (.claude/ directory, settings.json).

Proposed Solution

We propose extending the existing hooks system to support GitHub webhook events. This would allow developers to define "remote hooks" that are triggered by events in the repository, using the same familiar configuration paradigm as local hooks.

1. New Hook Event Types:

Introduce new hook event types in settings.json that correspond to GitHub webhook events, namespaced for clarity.

• github:issues.opened
• github:issues.labeled
• github:pull_request.opened
• github:pull_request.synchronize
• github:issue_comment.created
• github:push

2. Configuration in .claude/settings.json:

Users would configure these hooks just like existing ones. The scripts would live in the repository and be version-controlled alongside the code.

// in .claude/settings.json
{
  "hooks": {
    // --- Existing local hooks ---
    "PreToolUse": [/* ... */],
    "PostToolUse": [/* ... */],
    
    // --- Proposed remote GitHub hooks ---
    "github:issues.opened": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/triage-issue.sh"
          }
        ]
      }
    ],
    "github:pull_request.opened": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/run-pr-linter.sh"
          }
        ]
      }
    ]
  }
}

3. Execution Flow:

This feature would likely leverage the existing Claude GitHub App infrastructure.

1. A user installs/configures the Claude GitHub App on their repository to listen for the desired webhook events.
2. When a webhook fires (e.g., issues.opened), GitHub sends the event payload to an Anthropic-managed endpoint.
3. The backend service triggers a lightweight, containerized runner for the repository.
4. The runner checks out the code, reads the .claude/settings.json file to find the matching hook configuration.
5. It executes the specified command (e.g., .claude/hooks/triage-issue.sh), piping the full JSON payload of the GitHub webhook event to the script's stdin.

Example Use Cases

This would unlock many powerful, low-friction automation workflows:

• Automated Issue Triage (Agentic-in-a-Box): Combine scripting with a headless Claude call for intelligent labeling.
• Event: github:issues.opened
• Script (.claude/hooks/triage-issue.sh):

```bash
#!/bin/bash
# Read issue payload from stdin
PAYLOAD=$(cat)
ISSUE_BODY=$(echo "$PAYLOAD" | jq -r .issue.body)
ISSUE_NUMBER=$(echo "$PAYLOAD" | jq -r .issue.number)

# Use Claude to determine labels from a predefined list
LABELS=$(claude -p "Given this issue body, what labels from the list (bug, feature, docs, testing) should be applied? Respond with a comma-separated list only. Issue: '''$ISSUE_BODY'''")

# Use the gh CLI to apply labels
gh issue edit "$ISSUE_NUMBER" --add-label "$LABELS"
```

• PR Sanity Checks: Run a fast linter or formatter check on new PRs.
• Event: github:pull_request.opened
• Script: A shell script that checks out the PR branch, runs npm run lint, and posts a comment back to the PR with the results using the gh CLI.

• Documentation Reminders:
• Event: github:pull_request.synchronize
• Script: A script that uses git diff to check for changes to source code (/src) and verifies if corresponding changes were made to documentation (/docs). If not, it posts a gentle reminder comment on the PR.

Key Benefits

• Unified Developer Experience: Developers can use a single, consistent hooks paradigm for both local agent lifecycle events and remote repository events.
• Low-Friction Automation: Drastically lowers the barrier to entry for simple repository automation compared to authoring a full action.yml file.
• Version Controlled & Collaborative: Hooks and their scripts live in the .claude/ directory and are version-controlled with the codebase, making them transparent and collaborative.
• Leverages Claude Code's "Unix Philosophy": Enables powerful composition of shell scripting, the gh CLI, and programmatic calls to claude -p for agentic processing within deterministic scripts.

Implementation Considerations

• Execution Environment: The hook scripts would need to run in a secure, server-side environment managed by Anthropic, similar to the runners used for the existing GitHub Actions.
• Authentication: The execution environment would need access to a short-lived GITHUB_TOKEN (provided by the GitHub App infrastructure) to perform actions like commenting on PRs or adding labels.
• Setup: A simple setup process, perhaps via a command like /install-github-hooks, could be introduced to configure the necessary webhooks on the repository.

Alternatives Considered

1. Using the existing Claude Code GitHub Action: This is the current solution, but it is designed for complex, agentic tasks triggered by a user mention (@claude). It's not suited for simple, deterministic reactions to non-comment events.
2. Using standard GitHub Actions: This is a viable alternative, but it creates a separate automation system. The appeal of this feature request is to unify repository automation within the claude-code configuration (settings.json).
3. Building a custom webhook listener service: This is far too complex for most teams and requires hosting infrastructure, defeating the purpose of a simple, repository-based solution.

This feature would beautifully complement the existing local hooks and the mention-driven GitHub Action, creating a comprehensive, multi-layered automation toolkit for developers within the Claude Code ecosystem.