4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Adds title, description, type, domain, and tags frontmatter to every doc for improved KB semantic search. The description field is prepended to every search chunk, and domain/type/tags enable filtered queries. Type values: context, guide, runbook, reference, troubleshooting Domain values match directory structure (networking, docker, etc.) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
---
|
|
title: "Claude Agent Discord Notifications"
|
|
description: "Setup guide for the n8n workflow that sends Discord notifications when Claude Code subagents finish. Covers SubagentStop hook config, n8n webhook setup, Discord variable storage, payload reference, and testing."
|
|
type: guide
|
|
domain: productivity
|
|
tags: [n8n, claude-code, discord, webhook, subagent, notifications, automation]
|
|
---
|
|
|
|
# Claude Agent Done → Discord Notifications
|
|
|
|
Notifies a Discord channel via webhook when a Claude Code subagent finishes. Useful for long-running pipelines (10+ minutes) where you want a heads-up when work completes.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Claude Code (SubagentStop hook)
|
|
│
|
|
│ POST raw event JSON
|
|
▼
|
|
n8n Webhook: /webhook/claude-agent-done
|
|
│
|
|
│ Extract agent name, build message
|
|
▼
|
|
Discord Webhook (stored as n8n variable)
|
|
│
|
|
▼
|
|
"🏁 Claude agent **{name}** has finished."
|
|
```
|
|
|
|
### Why n8n as the middle layer?
|
|
|
|
Claude Code HTTP hooks send raw event JSON — you can't customize the body. Discord requires `{"content": "..."}`. n8n does the transformation and keeps the Discord webhook URL out of local config files.
|
|
|
|
## Setup
|
|
|
|
### 1. n8n workflow
|
|
|
|
Import `claude-agent-done.json` into n8n:
|
|
|
|
1. n8n → Workflows → Import from File → select `claude-agent-done.json`
|
|
2. Set the workflow to **Active**
|
|
3. Note the production webhook URL: `http://10.10.0.210:5678/webhook/claude-agent-done`
|
|
|
|
### 2. Discord webhook
|
|
|
|
1. Open the target Discord channel → Edit Channel → Integrations → Webhooks → New Webhook
|
|
2. Copy the webhook URL
|
|
|
|
### 3. n8n variable
|
|
|
|
Store the Discord URL so it stays out of config files:
|
|
|
|
1. n8n → Settings → Variables → Add Variable
|
|
2. **Key:** `DISCORD_CLAUDE_ALERTS_WEBHOOK`
|
|
3. **Value:** your Discord webhook URL
|
|
|
|
### 4. Claude Code hook config
|
|
|
|
The hook is configured in `.claude/settings.json` at the repo root:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"SubagentStop": [
|
|
{
|
|
"type": "http",
|
|
"url": "http://localhost:5678/webhook/claude-agent-done",
|
|
"async": true
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
> **Note:** Update `localhost:5678` to match your n8n host if running remotely (e.g. `http://10.10.0.210:5678`).
|
|
|
|
## Testing
|
|
|
|
Send a test payload to verify the pipeline end-to-end:
|
|
|
|
```bash
|
|
curl -X POST http://10.10.0.210:5678/webhook-test/claude-agent-done \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"hook_event_name": "SubagentStop", "session_id": "abc12345", "subagent_name": "test-agent"}'
|
|
```
|
|
|
|
Switch to `/webhook/` (not `/webhook-test/`) once confirmed working.
|
|
|
|
## Payload reference
|
|
|
|
Claude Code sends a JSON payload on `SubagentStop`. Known fields:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `hook_event_name` | Always `"SubagentStop"` |
|
|
| `session_id` | Agent session identifier |
|
|
| `subagent_name` | Name of the subagent (if set) |
|
|
|
|
The n8n workflow uses `subagent_name` if present, falling back to the first 8 chars of `session_id`.
|
|
|
|
## Future extensions
|
|
|
|
- Route different agent names to different Discord channels
|
|
- Add rich embeds with duration and success/failure status
|
|
- Filter by agent name (only notify for specific long-running pipelines)
|
|
- Route to local TTS/voice server for audio alerts
|
|
|
|
## Change Log
|
|
|
|
### 2026-03-04 - Initial setup
|
|
- Created n8n webhook workflow (`claude-agent-done.json`)
|
|
- Added `SubagentStop` HTTP hook to `.claude/settings.json`
|
|
- Discord webhook URL stored as n8n variable `DISCORD_CLAUDE_ALERTS_WEBHOOK`
|