English | 简体中文
A cross-editor AI programming notification gateway. Supports Cursor / Claude Code / Qoder. Real-time push notifications to desktop, mobile, and IM groups when AI tasks are completed, abnormally terminated, or waiting for authorization.
- Multi-editor Support — Cursor Hook, Claude Code Hook, Qoder log listening
- Multi-channel Notifications — Desktop system notifications, PWA web push, DingTalk, Feishu, WeCom
- Claude Code Deep Integration — Supports all Hook events like Stop / Notification / StopFailure / SessionEnd, customizable notification titles for each event
- Mobile Real-time Push — Built-in PWA Web App, HTTPS + WebSocket millisecond push, supports QR code connection
- Smart Anti-disturbance — Event deduplication + rate limiting to prevent message bombing
- Interactive Configuration —
agentwake setupguides you through all configurations step by step
- Node.js >= 18
- mkcert (Generates local HTTPS certificates, required for mobile push)
npm i -g agentwakeagentwake setup # Interactive setup (~/.agentwake/.env, HTTPS/mkcert, Cursor hooks, Claude hooks, channels, …)setup will guide you through:
- Whether to enable HTTPS (optional mkcert certificates)
- Select AI tools (Claude Code / Cursor / Qoder)
- Select event types to listen to (Claude)
- Customize notification titles for each event (optional)
- Select notification channels (DingTalk / Feishu / WeCom / PWA)
- Enter Webhook URLs and secrets (if applicable)
- Write Cursor
.cursor/hooks.json(if Cursor selected), install Claude Code hooks (if Claude selected) - Start the service (optional)
# Edit ~/.agentwake/.env manually (you can copy from the repo’s .env.example)
# Fill in values, then:
agentwake startAll data is stored in the ~/.agentwake/ directory, no need to create a working directory manually.
git clone https://github.com/tjdxwwj/agentwake.git
cd agentwake
npm install
# Interactive setup (.env, optional mkcert, hooks)
npm run setup
# Start development server
npm run devAfter starting, the service runs at https://localhost:3199.
| Channel | Configuration | Description |
|---|---|---|
| Desktop Notification | Built-in, no config needed | macOS / Windows / Linux |
| PWA Web Push | Built-in, open service URL in mobile browser | Requires HTTPS, supports Service Worker system notifications |
| DingTalk | AGENTWAKE_DINGTALK_WEBHOOK |
Group bot Webhook, supports signature verification |
| Feishu | AGENTWAKE_FEISHU_WEBHOOK |
Group bot Webhook, supports signature verification |
| WeCom | AGENTWAKE_WECOM_WEBHOOK |
Group bot Webhook, security guaranteed by URL Key |
- Open the DingTalk group → Group settings → Bot (机器人) → add or manage bots.
- Choose Custom (自定义) — “Access custom services via Webhook”, then complete the wizard and copy the Webhook URL and optional signing secret (加签).
Group settings → Bot (机器人).
Add robot → Custom — Webhook integration.
AGENTWAKE_DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx
AGENTWAKE_DINGTALK_SECRET=SECxxx # Optional, signature secret
Example messages: Claude Code “needs your attention” and Cursor “waiting for user approval” (group bot on mobile).
In Feishu Group -> Settings -> Bots -> Add Custom Bot, copy the Webhook URL.
AGENTWAKE_FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
AGENTWAKE_FEISHU_SECRET=xxx # Optional, signature verification secretIn WeCom Group -> Group Bots -> Add Group Bot, copy the Webhook URL.
AGENTWAKE_WECOM_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxRunning agentwake setup will automatically:
- Generate Hook relay script to
~/.agentwake/hooks/claude-hook-relay.sh - Write Hook configuration to
~/.claude/settings.json
Supported Hook events:
| Event | Description | Enabled by Default |
|---|---|---|
| Notification | Requires user attention | Yes |
| Stop | Task completed | Yes |
| StopFailure | Task terminated abnormally | Yes |
| SessionEnd | Session ended | Yes |
| SessionStart | Session started | No |
| PreToolUse | Before tool use | No |
| PostToolUse | After tool use | No |
- Run
agentwake setupat the project root and enable Cursor (writes.cursor/hooks.json) - Keep
agentwake startrunning - Automatic notification when Cursor terminal triggers authorization wait
Automatically discover log directory, or specify manually:
AGENTWAKE_QODER_LOG_PATH="/path/to/agent.log" agentwake startSet interactively via agentwake setup, or configure directly in .env:
AGENTWAKE_CLAUDE_TITLE_STOP=AI Done
AGENTWAKE_CLAUDE_TITLE_STOP_FAILURE=AI Failed
AGENTWAKE_CLAUDE_TITLE_NOTIFICATION=AI Needs Attention
AGENTWAKE_CLAUDE_TITLE_SESSION_END=Session EndedEvents without configured titles will use default titles.
Your phone needs to trust the local HTTPS certificate to receive Service Worker system notifications.
- Get root certificate path: run
mkcert -CAROOTto findrootCA.pem - Install on mobile:
- iOS — Send to phone, install profile, then enable full trust in Settings > General > About > Certificate Trust Settings
- Android — Install CA certificate in security settings (may need to rename extension to
.crt)
- Open
https://<LAN IP>:3199in mobile browser, confirm HTTPS connection is secure and allow notification permissions
| Variable | Default Value | Description |
|---|---|---|
AGENTWAKE_HOST |
0.0.0.0 |
Listening address |
AGENTWAKE_PORT |
3199 |
Listening port |
AGENTWAKE_HTTPS_ENABLED |
0 |
Enable HTTPS (1 to enable; mkcert can be run via agentwake setup) |
AGENTWAKE_HTTPS_CERT_PATH |
certs/dev-cert.pem |
HTTPS certificate path |
AGENTWAKE_HTTPS_KEY_PATH |
certs/dev-key.pem |
HTTPS private key path |
AGENTWAKE_CURSOR_ENABLED |
1 |
Enable Cursor hook adapter (0 to disable) |
AGENTWAKE_CLAUDE_ENABLED |
1 |
Enable Claude hook adapter (0 to disable) |
AGENTWAKE_QODER_ENABLED |
1 |
Enable Qoder log adapter (0 to disable) |
AGENTWAKE_DESKTOP_ENABLED |
1 |
Enable desktop system notifications (0 to disable) |
AGENTWAKE_PWA_ENABLED |
0 |
Enable PWA/WebSocket push (1 to enable; HTTPS recommended for mobile push) |
AGENTWAKE_DINGTALK_ENABLED |
1 |
Enable DingTalk notifications (0 to disable) |
AGENTWAKE_DINGTALK_WEBHOOK |
— | DingTalk Webhook URL |
AGENTWAKE_DINGTALK_SECRET |
— | DingTalk signature secret |
AGENTWAKE_FEISHU_ENABLED |
1 |
Enable Feishu notifications (0 to disable) |
AGENTWAKE_FEISHU_WEBHOOK |
— | Feishu Webhook URL |
AGENTWAKE_FEISHU_SECRET |
— | Feishu signature secret |
AGENTWAKE_WECOM_ENABLED |
1 |
Enable WeCom notifications (0 to disable) |
AGENTWAKE_WECOM_WEBHOOK |
— | WeCom Webhook URL |
AGENTWAKE_CLAUDE_TITLE_* |
— | Claude event custom titles |
AGENTWAKE_DEDUPE_WINDOW_MS |
10000 |
Deduplication window (ms) |
AGENTWAKE_RATE_LIMIT_WINDOW_MS |
10000 |
Rate limit window (ms) |
AGENTWAKE_RATE_LIMIT_MAX_EVENTS |
40 |
Max events within window |
AGENTWAKE_WS_PATH |
/ws |
WebSocket path |
AGENTWAKE_QODER_LOG_PATH |
— | Qoder log path (auto-discovered) |
AGENTWAKE_ALLOWED_HOOK_IPS |
— | Limit Hook source IPs (comma-separated) |
git clone https://github.com/tjdxwwj/agentwake.git
cd agentwake
npm install
npm run setup # Interactive ~/.agentwake/.env, optional mkcert
npm run dev # Start development server
npm test # Run testssrc/
adapters/ # Input adapters (Cursor / Claude / Qoder)
gateway/ # Core gateway (Adapter registration, event routing)
notifiers/ # Notification dispatchers (Desktop / WebSocket / DingTalk / Feishu / WeCom)
installers/ # Hook auto-installers
web/ # PWA frontend
Node.js + TypeScript + Express + WebSocket (ws) + Zod
Cannot receive notifications on mobile?
- Ensure phone and computer are on the same LAN
- Ensure browser shows secure HTTPS connection (not "Not Secure")
- Ensure notification permissions are granted
- Check if Web page WebSocket status is "Connected"
How to change port?
AGENTWAKE_PORT=4000 agentwake startCan personal WeChat receive notifications? WeChat does not support Webhook message push API. You can use WeCom group bots as an alternative.
MIT License