@delt/claude-alarm 0.3.1 → 0.3.4

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 (4) hide show
  1. package/README.md +201 -181
  2. package/dist/dashboard/index.html +9 -9
  3. package/package.json +1 -1
  4. package/src/dashboard/index.html +9 -9
package/README.md CHANGED
@@ -1,181 +1,201 @@
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
+ <p align="center">
10
+ <img src="docs/architecture.svg" alt="Architecture" width="800">
11
+ </p>
12
+
13
+ ## Features
14
+
15
+ - **Multi-Session Monitoring** — Real-time session status (idle / working / waiting)
16
+ - **Two-way Messaging** — Text + markdown + image exchange with Claude
17
+ - **Desktop Notifications** — Windows / macOS / Linux toast alerts
18
+ - **Token Auth** — Auto-generated secure access
19
+ - **Dark / Light Mode** — Theme toggle with persistence
20
+ - **Multi-Machine** — Remote hub access support
21
+
22
+ ## Quick Start
23
+
24
+ ### 1. Install
25
+
26
+ ```bash
27
+ npm install -g @delt/claude-alarm
28
+ ```
29
+
30
+ ### 2. Start the Hub
31
+
32
+ ```bash
33
+ claude-alarm hub start
34
+ ```
35
+
36
+ ### 3. Initialize Project
37
+
38
+ ```bash
39
+ cd your-project
40
+ claude-alarm init
41
+ ```
42
+
43
+ ### 4. Run Claude Code
44
+
45
+ ```bash
46
+ claude --dangerously-load-development-channels server:claude-alarm
47
+ ```
48
+
49
+ ### 5. Open Dashboard
50
+
51
+ Open `http://127.0.0.1:7900` in your browser.
52
+
53
+ ## Message Flow
54
+
55
+ <p align="center">
56
+ <img src="docs/message-flow.svg" alt="Message Flow" width="700">
57
+ </p>
58
+
59
+ ## Dashboard Layout
60
+
61
+ ```
62
+ ┌─────────────────────────────────────────────────────────────┐
63
+ │ Claude Alarm ☽ ● Connected │
64
+ ├──────────────┬──────────────────────┬───────────────────────┤
65
+ │ SESSIONS │ Messages │ NOTIFICATIONS │
66
+ │ │ │ │
67
+ │ ┌──────────┐ │ ┌─────────────────┐ │ ┌─────────────────┐ │
68
+ │ │ my-app │ │ │ Claude · 14:30 │ │ │ ● Task complete │ │
69
+ │ │ idle │ │ │ Build succeeded │ │ │ my-app · 14:30│ │
70
+ │ └──────────┘ │ └─────────────────┘ │ └─────────────────┘ │
71
+ │ ┌──────────┐ │ │ ┌─────────────────┐ │
72
+ │ │ api-svc │ │ ┌────────────┐ │ │ ● Error found │ │
73
+ │ │ working │ │ │ You · 14:31│ │ │ api-svc · 14:2│ │
74
+ │ └──────────┘ │ │ Fix the bug│ │ └─────────────────┘ │
75
+ │ ┌──────────┐ │ └────────────┘ │ │
76
+ │ │ frontend │ │ │ │
77
+ │ │ waiting │ │ │ │
78
+ │ └──────────┘ │ │ │
79
+ ├──────────────┴──────────────────────┴───────────────────────┤
80
+ │ 📎 [Message input... Shift+Enter ↵] [ Send ] │
81
+ └─────────────────────────────────────────────────────────────┘
82
+ ```
83
+
84
+ ## CLI Commands
85
+
86
+ | Command | Description |
87
+ |---------|-------------|
88
+ | `claude-alarm init` | Setup project and show next steps |
89
+ | `claude-alarm hub start [-d]` | Start hub server (`-d` for daemon) |
90
+ | `claude-alarm hub stop` | Stop hub daemon |
91
+ | `claude-alarm hub status` | Show hub status |
92
+ | `claude-alarm token` | Show auth token |
93
+ | `claude-alarm test` | Send test notification |
94
+
95
+ ## Tools Available to Claude
96
+
97
+ | Tool | Description |
98
+ |------|-------------|
99
+ | `notify` | Send a desktop notification (title, message, level) |
100
+ | `reply` | Send a message to the dashboard |
101
+ | `status` | Update session status (idle, working, waiting_input) |
102
+
103
+ ## Configuration
104
+
105
+ Config stored at `~/.claude-alarm/config.json`:
106
+
107
+ ```json
108
+ {
109
+ "hub": {
110
+ "host": "127.0.0.1",
111
+ "port": 7900,
112
+ "token": "auto-generated-uuid"
113
+ },
114
+ "notifications": {
115
+ "desktop": true,
116
+ "sound": true
117
+ },
118
+ "webhooks": []
119
+ }
120
+ ```
121
+
122
+ ### Custom Session Names
123
+
124
+ ```json
125
+ {
126
+ "mcpServers": {
127
+ "claude-alarm": {
128
+ "command": "npx",
129
+ "args": ["-y", "@delt/claude-alarm", "serve"],
130
+ "env": {
131
+ "CLAUDE_ALARM_SESSION_NAME": "my-project"
132
+ }
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ ### Webhooks
139
+
140
+ ```json
141
+ {
142
+ "webhooks": [
143
+ {
144
+ "url": "https://hooks.slack.com/services/...",
145
+ "headers": { "Content-Type": "application/json" }
146
+ }
147
+ ]
148
+ }
149
+ ```
150
+
151
+ ## Remote Access
152
+
153
+ <p align="center">
154
+ <img src="docs/remote-access.svg" alt="Remote Access" width="600">
155
+ </p>
156
+
157
+ 1. Set host to `0.0.0.0` in `~/.claude-alarm/config.json`
158
+ 2. Open port 7900 in your firewall
159
+ 3. On remote machine: `claude-alarm init` → select remote hub (Y)
160
+
161
+ ```json
162
+ {
163
+ "mcpServers": {
164
+ "claude-alarm": {
165
+ "command": "npx",
166
+ "args": ["-y", "@delt/claude-alarm", "serve"],
167
+ "env": {
168
+ "CLAUDE_ALARM_HUB_HOST": "your-server-ip",
169
+ "CLAUDE_ALARM_HUB_PORT": "7900",
170
+ "CLAUDE_ALARM_HUB_TOKEN": "your-token"
171
+ }
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ ## Image Upload (Local Sessions)
178
+
179
+ Send images to Claude via the dashboard:
180
+ - **Ctrl+V** — Paste from clipboard
181
+ - **Drag & Drop** — Drop image onto message area
182
+ - **Attach button** — Click 📎 to browse files
183
+
184
+ > Images are only available for local sessions (same machine as Hub). Max 10MB, auto-deleted after 5 minutes.
185
+
186
+ ## Platform Support
187
+
188
+ | Platform | Notifications | Engine |
189
+ |----------|:---:|--------|
190
+ | Windows | ✓ | SnoreToast |
191
+ | macOS | ✓ | terminal-notifier |
192
+ | Linux | ✓ | notify-send |
193
+
194
+ ## Requirements
195
+
196
+ - Node.js >= 18
197
+ - Claude Code with MCP Channels support
198
+
199
+ ## License
200
+
201
+ MIT
package/dist/dashboard/index.html CHANGED
@@ -11,10 +11,10 @@
11
11
  --border: #2a2d3a;
12
12
  --text: #e1e4ed;
13
13
  --text-dim: #8b8fa3;
14
- --accent: #7c6aef;
15
- --accent-dim: #5a4db8;
14
+ --accent: #e0a86d;
15
+ --accent-dim: #c48d52;
16
16
  --green: #3dd68c;
17
- --yellow: #f5c542;
17
+ --yellow: #f59e0b;
18
18
  --red: #ef4444;
19
19
  --blue: #60a5fa;
20
20
  }
@@ -24,10 +24,10 @@
24
24
  --border: #d1d5db;
25
25
  --text: #1f2937;
26
26
  --text-dim: #6b7280;
27
- --accent: #7c6aef;
28
- --accent-dim: #5a4db8;
27
+ --accent: #c48d52;
28
+ --accent-dim: #a87642;
29
29
  --green: #22c55e;
30
- --yellow: #eab308;
30
+ --yellow: #d97706;
31
31
  --red: #ef4444;
32
32
  --blue: #3b82f6;
33
33
  }
@@ -172,8 +172,8 @@
172
172
  border: 1px solid var(--border);
173
173
  }
174
174
  .message.from-dashboard {
175
- background: rgba(124,106,239,0.12);
176
- border: 1px solid rgba(124,106,239,0.25);
175
+ background: rgba(224,168,109,0.12);
176
+ border: 1px solid rgba(224,168,109,0.25);
177
177
  margin-left: auto;
178
178
  }
179
179
  .message-meta {
@@ -223,7 +223,7 @@
223
223
  .drag-overlay {
224
224
  position: absolute;
225
225
  inset: 0;
226
- background: rgba(124,106,239,0.15);
226
+ background: rgba(224,168,109,0.15);
227
227
  border: 2px dashed var(--accent);
228
228
  border-radius: 8px;
229
229
  display: none;
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.4",
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",
package/src/dashboard/index.html CHANGED
@@ -11,10 +11,10 @@
11
11
  --border: #2a2d3a;
12
12
  --text: #e1e4ed;
13
13
  --text-dim: #8b8fa3;
14
- --accent: #7c6aef;
15
- --accent-dim: #5a4db8;
14
+ --accent: #e0a86d;
15
+ --accent-dim: #c48d52;
16
16
  --green: #3dd68c;
17
- --yellow: #f5c542;
17
+ --yellow: #f59e0b;
18
18
  --red: #ef4444;
19
19
  --blue: #60a5fa;
20
20
  }
@@ -24,10 +24,10 @@
24
24
  --border: #d1d5db;
25
25
  --text: #1f2937;
26
26
  --text-dim: #6b7280;
27
- --accent: #7c6aef;
28
- --accent-dim: #5a4db8;
27
+ --accent: #c48d52;
28
+ --accent-dim: #a87642;
29
29
  --green: #22c55e;
30
- --yellow: #eab308;
30
+ --yellow: #d97706;
31
31
  --red: #ef4444;
32
32
  --blue: #3b82f6;
33
33
  }
@@ -172,8 +172,8 @@
172
172
  border: 1px solid var(--border);
173
173
  }
174
174
  .message.from-dashboard {
175
- background: rgba(124,106,239,0.12);
176
- border: 1px solid rgba(124,106,239,0.25);
175
+ background: rgba(224,168,109,0.12);
176
+ border: 1px solid rgba(224,168,109,0.25);
177
177
  margin-left: auto;
178
178
  }
179
179
  .message-meta {
@@ -223,7 +223,7 @@
223
223
  .drag-overlay {
224
224
  position: absolute;
225
225
  inset: 0;
226
- background: rgba(124,106,239,0.15);
226
+ background: rgba(224,168,109,0.15);
227
227
  border: 2px dashed var(--accent);
228
228
  border-radius: 8px;
229
229
  display: none;