github-channels

Claude Code plugin that streams GitHub webhook events into your session in real-time. Push, PR, issue, CI — perceived as they happen, not polled.

Install

# Add the marketplace (one-time)
claude plugins marketplace add mlops-kelvin/github-channels

# Install the plugin
claude plugins install github-channels

Restart Claude Code after installing. The plugin registers its MCP server automatically. On first run, it:

• Creates a config template at ~/.claude/channels/github-channels/config.json

• Auto-generates a webhook secret at ~/.github-channels-secret

Related MCP server: github-workflow-mcp

Configure

Edit ~/.claude/channels/github-channels/config.json:

{
  "port": 8789,
  "repos": ["owner/repo-a", "owner/repo-b"],
  "events": ["push", "pull_request", "issues", "issue_comment", "pull_request_review"],
  "trusted_actors": ["your-username", "teammate"],
  "channel_tip": "Tip: curl -X POST localhost:8789/mute/owner/repo?hours=5 to mute a noisy repo."
}

Set up GitHub webhooks

On each monitored repo: Settings > Webhooks > Add webhook

• Payload URL: https://your-domain.com/webhook

• Content type: application/json

• Secret: contents of ~/.github-channels-secret

• Events: select the events matching your config

Reverse proxy

The server binds to 127.0.0.1:8789 (localhost only). A reverse proxy must forward /webhook to it so GitHub can deliver events. TLS termination happens at the proxy, not the plugin.

Angie / nginx:

location /webhook {
    proxy_pass http://127.0.0.1:8789/webhook;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Only allow POST (webhooks are always POST)
    limit_except POST { deny all; }
}

Security hardening (optional but recommended):

• Restrict to GitHub's webhook IP ranges (hooks key) at the proxy level

• Add rate limiting at the proxy (limit_req_zone in nginx/Angie)

• Never expose port 8789 directly to the internet — always proxy

Verify the proxy works:

# Should return 401 (invalid signature) — proves the proxy forwards to the server
curl -X POST https://your-domain.com/webhook -H "Content-Type: application/json" -d '{}'

Start Claude Code

claude --dangerously-load-development-channels plugin:github-channels@github-channels

This tells Claude Code to treat the plugin's MCP server as a development channel. Without this flag, the MCP server runs but events won't stream into your session.

With Discord plugin (both channels active):

claude --dangerously-load-development-channels plugin:github-channels@github-channels --channels plugin:discord@claude-plugins-official

• --dangerously-load-development-channels: for third-party plugins (bypasses Anthropic's channel allowlist)

• --channels: for official plugins (on the allowlist)

Verify

curl localhost:8789/status

Check:

• mcp_connected: true — Claude Code has connected

• channels_ready: true — events will flow

• counts.delivered — number of events pushed to your session

Control

curl -X POST localhost:8789/mute                       # mute all
curl -X POST localhost:8789/unmute                     # unmute all
curl -X POST localhost:8789/mute/owner/repo?hours=5    # mute repo for 5h
curl -X POST localhost:8789/unmute/owner/repo          # unmute repo
curl -X POST localhost:8789/mute-all?hours=8           # mute all repos for 8h
curl -X POST localhost:8789/unmute-all                 # unmute everything

Event Format

<channel source="github" event_type="push" repo="owner/repo" author="username" trust_tier="team" action="">
username pushed 3 commit(s) to owner/repo/main
  - Fix login validation
  - Update tests
  - Bump version
</channel>

Supported Events

Troubleshooting

Security

• HMAC-SHA256 verification on every webhook (secret required)

• Server binds to localhost only

• Trust tiers: team (in trusted_actors) vs external (everyone else)

• Content truncated to 2000 chars to prevent context flooding

• Agent instructions include prompt injection response protocol

Development

bun test
bun run dev

License

MIT — Marbell AG