@delt/claude-alarm 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +262 -181
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,181 +1,262 @@
1
- # claude-alarm
2
-
3
- Monitor and interact with multiple Claude Code sessions from a web dashboard. Get desktop notifications when tasks complete, send messages to Claude, and track session status — all through MCP Channels.
4
-
5
- ```
6
- [Dashboard] ──message──> [Hub Server] ──WebSocket──> [Channel Server] ──> Claude Code
7
- <──
8
- Claude Code ──reply/notify──> [Channel Server] ──> [Hub Server] ──> [Dashboard]
9
- ```
10
-
11
- ## Features
12
-
13
- - **Web Dashboard** — Monitor all Claude Code sessions in one place
14
- - **Two-way Messaging** — Send messages to Claude and receive replies (with markdown rendering)
15
- - **Desktop Notifications** — Get Windows/macOS/Linux toast notifications
16
- - **Session Status** — See which sessions are idle, working, or waiting for input
17
- - **Token Auth** — Secure hub access with auto-generated tokens
18
- - **Multi-session** — Connect multiple Claude Code instances simultaneously
19
-
20
- ## Quick Start
21
-
22
- ### 1. Install & Initialize
23
-
24
- In your project directory:
25
-
26
- ```bash
27
- npx @delt/claude-alarm init
28
- ```
29
-
30
- This creates `.mcp.json` with the claude-alarm channel server config.
31
-
32
- ### 2. Start the Hub
33
-
34
- ```bash
35
- npx @delt/claude-alarm hub start
36
- ```
37
-
38
- This starts the hub server and prints your auth token.
39
-
40
- ### 3. Run Claude Code
41
-
42
- ```bash
43
- claude --dangerously-load-development-channels server:claude-alarm
44
- ```
45
-
46
- To allow remote control without approval prompts:
47
-
48
- ```bash
49
- claude --dangerously-load-development-channels server:claude-alarm --dangerously-skip-permissions
50
- ```
51
-
52
- > **WARNING:** `--dangerously-skip-permissions` allows Claude to execute any action without your approval. Only use in trusted, isolated environments.
53
-
54
- ### 4. Open Dashboard
55
-
56
- Open `http://127.0.0.1:7900` in your browser.
57
-
58
- ## CLI Commands
59
-
60
- ```
61
- claude-alarm init Setup everything and show next steps
62
- claude-alarm hub start [-d] Start the hub server (-d for daemon mode)
63
- claude-alarm hub stop Stop the hub daemon
64
- claude-alarm hub status Show hub status
65
- claude-alarm setup [dir] Add claude-alarm to .mcp.json
66
- claude-alarm test Send a test notification
67
- claude-alarm token Show current auth token
68
- ```
69
-
70
- ## How It Works
71
-
72
- claude-alarm uses [MCP Channels](https://modelcontextprotocol.io) to create a communication bridge between Claude Code and a web dashboard.
73
-
74
- - **Hub Server** — Central server that manages sessions, serves the dashboard, and routes messages
75
- - **Channel Server** — MCP server that runs inside Claude Code, providing tools and forwarding messages
76
- - **Dashboard** — Web UI for monitoring sessions and sending messages
77
-
78
- ### Tools Available to Claude
79
-
80
- | Tool | Description |
81
- |------|-------------|
82
- | `notify` | Send a desktop notification (title, message, level) |
83
- | `reply` | Send a message to the dashboard |
84
- | `status` | Update session status (idle, working, waiting_input) |
85
-
86
- ## Configuration
87
-
88
- Config is stored at `~/.claude-alarm/config.json`:
89
-
90
- ```json
91
- {
92
- "hub": {
93
- "host": "127.0.0.1",
94
- "port": 7900,
95
- "token": "auto-generated-uuid"
96
- },
97
- "notifications": {
98
- "desktop": true,
99
- "sound": true
100
- },
101
- "webhooks": []
102
- }
103
- ```
104
-
105
- ### Custom Session Names
106
-
107
- The `.mcp.json` created by `claude-alarm init` automatically uses the project directory name as the session name. You can customize it:
108
-
109
- ```json
110
- {
111
- "mcpServers": {
112
- "claude-alarm": {
113
- "command": "npx",
114
- "args": ["-y", "@delt/claude-alarm", "serve"],
115
- "env": {
116
- "CLAUDE_ALARM_SESSION_NAME": "my-project"
117
- }
118
- }
119
- }
120
- }
121
- ```
122
-
123
- ### Webhooks
124
-
125
- Send notifications to external services:
126
-
127
- ```json
128
- {
129
- "webhooks": [
130
- {
131
- "url": "https://hooks.slack.com/services/...",
132
- "headers": { "Content-Type": "application/json" }
133
- }
134
- ]
135
- }
136
- ```
137
-
138
- ## Remote Access
139
-
140
- To access the hub from another machine:
141
-
142
- 1. Set host to `0.0.0.0` in `~/.claude-alarm/config.json`
143
- 2. Open port 7900 in your firewall
144
- 3. On the remote machine, run `claude-alarm init` and select remote hub (Y), or manually set `.mcp.json`:
145
-
146
- ```json
147
- {
148
- "mcpServers": {
149
- "claude-alarm": {
150
- "command": "npx",
151
- "args": ["-y", "@delt/claude-alarm", "serve"],
152
- "env": {
153
- "CLAUDE_ALARM_HUB_HOST": "your-server-ip",
154
- "CLAUDE_ALARM_HUB_PORT": "7900",
155
- "CLAUDE_ALARM_HUB_TOKEN": "your-token"
156
- }
157
- }
158
- }
159
- }
160
- ```
161
-
162
- ## Platform Support
163
-
164
- Desktop notifications work across all major platforms via [node-notifier](https://github.com/mikaelbr/node-notifier):
165
-
166
- | Platform | Notification Engine | Click to Open |
167
- |----------|-------------------|---------------|
168
- | Windows | SnoreToast (built-in) | `Start-Process` |
169
- | macOS | terminal-notifier | `open` |
170
- | Linux | notify-send (libnotify) | `xdg-open` |
171
-
172
- No additional setup needed — `node-notifier` automatically detects your OS and uses the appropriate tool.
173
-
174
- ## Requirements
175
-
176
- - Node.js >= 18
177
- - Claude Code with MCP Channels support
178
-
179
- ## License
180
-
181
- MIT
1
+ # claude-alarm
2
+
3
+ > Multi-session monitoring dashboard for Claude Code via MCP Channels
4
+
5
+ Monitor and interact with multiple Claude Code sessions from a web dashboard. Get desktop notifications when tasks complete, send messages to Claude, and track session status.
6
+
7
+ ## Architecture
8
+
9
+ ```mermaid
10
+ graph LR
11
+ subgraph "Your Machine"
12
+ CC1["Claude Code<br/>(Session 1)"] --> CS1["Channel Server"]
13
+ CC2["Claude Code<br/>(Session 2)"] --> CS2["Channel Server"]
14
+ CC3["Claude Code<br/>(Session 3)"] --> CS3["Channel Server"]
15
+ end
16
+
17
+ CS1 -->|WebSocket| HUB["Hub Server<br/>:7900"]
18
+ CS2 -->|WebSocket| HUB
19
+ CS3 -->|WebSocket| HUB
20
+
21
+ HUB -->|HTTP| DASH["Web Dashboard"]
22
+ HUB -->|Toast| NOTIF["Desktop<br/>Notifications"]
23
+
24
+ subgraph "Remote Machine (optional)"
25
+ CC4["Claude Code<br/>(Session 4)"] --> CS4["Channel Server"]
26
+ end
27
+ CS4 -->|WebSocket| HUB
28
+
29
+ style HUB fill:#7c6aef,stroke:#5a4db8,color:#fff
30
+ style DASH fill:#3dd68c,stroke:#22a06b,color:#000
31
+ style NOTIF fill:#f5c542,stroke:#d4a72c,color:#000
32
+ ```
33
+
34
+ ## Features
35
+
36
+ ```mermaid
37
+ graph TD
38
+ A["Multi-Session<br/>Monitoring"] --> |"real-time"| B["Session Status<br/>idle · working · waiting"]
39
+ A --> |"two-way"| C["Message Exchange<br/>text + markdown + images"]
40
+ A --> |"alerts"| D["Desktop Notifications<br/>Windows · macOS · Linux"]
41
+ A --> |"security"| E["Token Auth<br/>auto-generated"]
42
+ A --> |"theme"| F["Dark / Light Mode"]
43
+ A --> |"remote"| G["Multi-Machine<br/>Support"]
44
+
45
+ style A fill:#7c6aef,stroke:#5a4db8,color:#fff
46
+ style B fill:#60a5fa,stroke:#3b82f6,color:#000
47
+ style C fill:#3dd68c,stroke:#22a06b,color:#000
48
+ style D fill:#f5c542,stroke:#d4a72c,color:#000
49
+ style E fill:#ef4444,stroke:#dc2626,color:#fff
50
+ style F fill:#8b8fa3,stroke:#6b7280,color:#fff
51
+ style G fill:#a78bfa,stroke:#7c3aed,color:#000
52
+ ```
53
+
54
+ ## Quick Start
55
+
56
+ ### 1. Install
57
+
58
+ ```bash
59
+ npm install -g @delt/claude-alarm
60
+ ```
61
+
62
+ ### 2. Start the Hub
63
+
64
+ ```bash
65
+ claude-alarm hub start
66
+ ```
67
+
68
+ ### 3. Initialize Project
69
+
70
+ ```bash
71
+ cd your-project
72
+ claude-alarm init
73
+ ```
74
+
75
+ ### 4. Run Claude Code
76
+
77
+ ```bash
78
+ claude --dangerously-load-development-channels server:claude-alarm
79
+ ```
80
+
81
+ ### 5. Open Dashboard
82
+
83
+ Open `http://127.0.0.1:7900` in your browser.
84
+
85
+ ## Message Flow
86
+
87
+ ```mermaid
88
+ sequenceDiagram
89
+ participant D as Dashboard
90
+ participant H as Hub Server
91
+ participant C as Channel Server
92
+ participant CC as Claude Code
93
+
94
+ D->>H: Send message
95
+ H->>C: Forward via WebSocket
96
+ C->>CC: MCP Channel notification
97
+ CC->>CC: Process & execute
98
+ CC->>C: Call reply tool
99
+ C->>H: Forward reply
100
+ H->>D: Display in chat
101
+ H->>H: Desktop notification
102
+ ```
103
+
104
+ ## Dashboard Layout
105
+
106
+ ```
107
+ ┌─────────────────────────────────────────────────────────────┐
108
+ │ Claude Alarm ☽ ● Connected │
109
+ ├──────────────┬──────────────────────┬───────────────────────┤
110
+ │ SESSIONS │ Messages │ NOTIFICATIONS │
111
+ │ │ │ │
112
+ │ ┌──────────┐ │ ┌─────────────────┐ │ ┌─────────────────┐ │
113
+ │ │ my-app │ │ │ Claude · 14:30 │ │ │ ● Task complete │ │
114
+ │ │ idle │ │ │ Build succeeded │ │ │ my-app · 14:30│ │
115
+ │ └──────────┘ │ └─────────────────┘ │ └─────────────────┘ │
116
+ │ ┌──────────┐ │ │ ┌─────────────────┐ │
117
+ │ │ api-svc │ │ ┌────────────┐ │ │ ● Error found │ │
118
+ │ │ working │ │ │ You · 14:31│ │ │ api-svc · 14:2│ │
119
+ │ └──────────┘ │ │ Fix the bug│ │ └─────────────────┘ │
120
+ │ ┌──────────┐ │ └────────────┘ │ │
121
+ │ │ frontend │ │ │ │
122
+ │ │ waiting │ │ │ │
123
+ │ └──────────┘ │ │ │
124
+ ├──────────────┴──────────────────────┴───────────────────────┤
125
+ │ 📎 [Message input... Shift+Enter ↵] [ Send ] │
126
+ └─────────────────────────────────────────────────────────────┘
127
+ ```
128
+
129
+ ## CLI Commands
130
+
131
+ | Command | Description |
132
+ |---------|-------------|
133
+ | `claude-alarm init` | Setup project and show next steps |
134
+ | `claude-alarm hub start [-d]` | Start hub server (`-d` for daemon) |
135
+ | `claude-alarm hub stop` | Stop hub daemon |
136
+ | `claude-alarm hub status` | Show hub status |
137
+ | `claude-alarm token` | Show auth token |
138
+ | `claude-alarm test` | Send test notification |
139
+
140
+ ## Tools Available to Claude
141
+
142
+ | Tool | Description |
143
+ |------|-------------|
144
+ | `notify` | Send a desktop notification (title, message, level) |
145
+ | `reply` | Send a message to the dashboard |
146
+ | `status` | Update session status (idle, working, waiting_input) |
147
+
148
+ ## Configuration
149
+
150
+ Config stored at `~/.claude-alarm/config.json`:
151
+
152
+ ```json
153
+ {
154
+ "hub": {
155
+ "host": "127.0.0.1",
156
+ "port": 7900,
157
+ "token": "auto-generated-uuid"
158
+ },
159
+ "notifications": {
160
+ "desktop": true,
161
+ "sound": true
162
+ },
163
+ "webhooks": []
164
+ }
165
+ ```
166
+
167
+ ### Custom Session Names
168
+
169
+ ```json
170
+ {
171
+ "mcpServers": {
172
+ "claude-alarm": {
173
+ "command": "npx",
174
+ "args": ["-y", "@delt/claude-alarm", "serve"],
175
+ "env": {
176
+ "CLAUDE_ALARM_SESSION_NAME": "my-project"
177
+ }
178
+ }
179
+ }
180
+ }
181
+ ```
182
+
183
+ ### Webhooks
184
+
185
+ ```json
186
+ {
187
+ "webhooks": [
188
+ {
189
+ "url": "https://hooks.slack.com/services/...",
190
+ "headers": { "Content-Type": "application/json" }
191
+ }
192
+ ]
193
+ }
194
+ ```
195
+
196
+ ## Remote Access
197
+
198
+ ```mermaid
199
+ graph LR
200
+ subgraph "Hub PC"
201
+ HUB["Hub Server<br/>0.0.0.0:7900"]
202
+ end
203
+
204
+ subgraph "Remote PC"
205
+ RC["Claude Code"] --> RCS["Channel Server"]
206
+ end
207
+
208
+ subgraph "Browser (any device)"
209
+ DASH["Dashboard"]
210
+ end
211
+
212
+ RCS -->|"WS + token"| HUB
213
+ DASH -->|"HTTP + token"| HUB
214
+
215
+ style HUB fill:#7c6aef,stroke:#5a4db8,color:#fff
216
+ ```
217
+
218
+ 1. Set host to `0.0.0.0` in `~/.claude-alarm/config.json`
219
+ 2. Open port 7900 in your firewall
220
+ 3. On remote machine: `claude-alarm init` → select remote hub (Y)
221
+
222
+ ```json
223
+ {
224
+ "mcpServers": {
225
+ "claude-alarm": {
226
+ "command": "npx",
227
+ "args": ["-y", "@delt/claude-alarm", "serve"],
228
+ "env": {
229
+ "CLAUDE_ALARM_HUB_HOST": "your-server-ip",
230
+ "CLAUDE_ALARM_HUB_PORT": "7900",
231
+ "CLAUDE_ALARM_HUB_TOKEN": "your-token"
232
+ }
233
+ }
234
+ }
235
+ }
236
+ ```
237
+
238
+ ## Image Upload (Local Sessions)
239
+
240
+ Send images to Claude via the dashboard:
241
+ - **Ctrl+V** — Paste from clipboard
242
+ - **Drag & Drop** — Drop image onto message area
243
+ - **Attach button** — Click 📎 to browse files
244
+
245
+ > Images are only available for local sessions (same machine as Hub). Max 10MB, auto-deleted after 5 minutes.
246
+
247
+ ## Platform Support
248
+
249
+ | Platform | Notifications | Engine |
250
+ |----------|:---:|--------|
251
+ | Windows | ✓ | SnoreToast |
252
+ | macOS | ✓ | terminal-notifier |
253
+ | Linux | ✓ | notify-send |
254
+
255
+ ## Requirements
256
+
257
+ - Node.js >= 18
258
+ - Claude Code with MCP Channels support
259
+
260
+ ## License
261
+
262
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@delt/claude-alarm",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "Monitor and get notifications from multiple Claude Code sessions via MCP Channels",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",