claude-channel-github-webhook

A Claude Code Channel plugin that delivers GitHub Webhook events as real-time notifications to your Claude Code session.

Supports PR reviews, CI failures, and @claude mentions.

Architecture

GitHub Webhook
      |
      v  (tunnel: ngrok / cloudflared / etc.)
[channel.ts :8788]  <- single process: MCP server + HTTP listener
      |
      v  (notifications/claude/channel)
Claude Code session

A single process handles everything: receives GitHub Webhooks over HTTP and forwards them to Claude Code via MCP stdio. No router, no registry, no extra processes.

Notification Rules

| Event | Condition | |---|---| | pull_request_review | All reviews | | check_run | conclusion === "failure" only | | issue_comment | Comment body contains @claude |

Setup

1. Install

npm install claude-channel-github-webhook

Or clone directly:

git clone https://github.com/moeki0/claude-channel-github-webhook.git
cd claude-channel-github-webhook
npm install

2. Open a tunnel

ngrok http 8788

Any tunneling tool works (ngrok, cloudflared, Smee.io, reverse proxy, etc.).

3. Configure the GitHub Webhook

In your repository's Settings > Webhooks > Add webhook:

• Payload URL: Your tunnel's public URL
• Content type: application/json
• Secret: Any string (optional but recommended)
• Events: Pull request reviews / Check runs / Issue comments

4. Launch with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "github-webhook": {
      "command": "npx",
      "args": ["claude-channel-github-webhook"],
      "env": {
        "GITHUB_WEBHOOK_SECRET": "your_secret"
      }
    }
  }
}

Then start Claude Code:

claude --dangerously-load-development-channels server:github-webhook

Environment Variables

| Variable | Description | Default | |---|---|---| | GITHUB_WEBHOOK_SECRET | Secret for HMAC signature verification | None (verification skipped) | | WEBHOOK_PORT | HTTP listen port | 8788 |

How It Works

1. Claude Code spawns channel.ts as a child process
2. The process connects to Claude Code via MCP stdio
3. It starts an HTTP server on 127.0.0.1:8788
4. GitHub Webhooks arrive via tunnel, are verified (HMAC), parsed, and filtered
5. Matching events are sent as notifications/claude/channel with structured meta attributes
6. Claude Code receives <channel source="github-webhook" event="check_run" ...> tags and acts accordingly

What Claude Receives

<channel source="github-webhook" event="check_run" conclusion="failure" branch="feat/x" workflow="CI / test">
CI failed: CI / test
Branch: feat/x
Details: https://github.com/org/repo/actions/runs/123
</channel>

Development

npm test        # Run tests
npm run lint    # Type check
npm run start   # Start channel standalone

Status

Claude Code Channels is in Research Preview.

• Requires Claude Code v2.1.80+
• Requires claude.ai login (not API key)
• Team/Enterprise orgs must enable channelsEnabled