mattermost-claude-code 0.5.0 → 0.5.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 (4) hide show
  1. package/README.md +194 -101
  2. package/dist/config.js +11 -4
  3. package/dist/index.js +1 -0
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -3,7 +3,17 @@
3
3
  [![npm version](https://img.shields.io/npm/v/mattermost-claude-code.svg)](https://www.npmjs.com/package/mattermost-claude-code)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
5
 
6
- Share your Claude Code sessions live in a public Mattermost channel. Your colleagues can watch you work with Claude Code in real-time, and authorized users can even trigger sessions from Mattermost.
6
+ Share Claude Code sessions live in a Mattermost channel. Your colleagues can watch you work with Claude in real-time, collaborate on sessions, and even trigger their own sessions from Mattermost.
7
+
8
+ ## Features
9
+
10
+ - **Real-time streaming** - Claude's responses stream live to Mattermost
11
+ - **Multiple concurrent sessions** - Each thread gets its own Claude session
12
+ - **Session collaboration** - Invite others to participate in your session
13
+ - **Interactive permissions** - Approve Claude's actions via emoji reactions
14
+ - **Plan approval** - Review and approve Claude's plans before execution
15
+ - **Task tracking** - Live todo list updates as Claude works
16
+ - **Code diffs** - See exactly what Claude is changing
7
17
 
8
18
  ## How it works
9
19
 
@@ -11,159 +21,242 @@ Share your Claude Code sessions live in a public Mattermost channel. Your collea
11
21
  ┌─────────────────────────────────────────────────────────────────┐
12
22
  │ Your Local Machine │
13
23
  │ ┌─────────────────┐ ┌─────────────────────────────┐ │
14
- │ │ Claude Code CLI │◄───────►│ This service │ │
15
- │ │ (subprocess) │ stdio │ (Node.js) │ │
24
+ │ │ Claude Code CLI │◀───────▶│ mm-claude │ │
25
+ │ │ (subprocess) │ stdio │ (this service) │ │
16
26
  │ └─────────────────┘ └──────────┬──────────────────┘ │
17
27
  └─────────────────────────────────────────┼───────────────────────┘
18
28
  │ WebSocket + REST API
19
- ▼ (outbound only!)
29
+ ▼ (outbound only)
20
30
  ┌─────────────────────────────────────────────────────────────────┐
21
31
  │ Mattermost Server │
22
32
  │ ┌─────────────────┐ ┌─────────────────────────────┐ │
23
- │ │ Bot Account │ │ Public Channel │ │
24
- │ │ @claude-code │◄───────►│ #claude-code-sessions │ │
33
+ │ │ Bot Account │◀───────▶│ Channel │ │
34
+ │ │ @claude-code │ │ #claude-sessions │ │
25
35
  │ └─────────────────┘ └─────────────────────────────┘ │
26
36
  └─────────────────────────────────────────────────────────────────┘
27
37
  ```
28
38
 
29
- This runs entirely on your local machine - it only makes **outbound** connections to Mattermost. No port forwarding or public IP needed!
39
+ Runs entirely on your machine - only **outbound** connections to Mattermost. No port forwarding needed!
30
40
 
31
41
  ## Prerequisites
32
42
 
33
43
  1. **Claude Code CLI** installed and authenticated (`claude --version`)
34
44
  2. **Node.js 18+**
35
- 3. **Mattermost bot account** with personal access token (ask your admin)
45
+ 3. **Mattermost bot account** with a personal access token
36
46
 
37
- ## Installation
47
+ ## Quick Start
48
+
49
+ ### 1. Install
38
50
 
39
- ### Option 1: npm (recommended)
40
51
  ```bash
41
52
  npm install -g mattermost-claude-code
42
53
  ```
43
54
 
44
- ### Option 2: From source
55
+ ### 2. Run
56
+
45
57
  ```bash
46
- git clone https://github.com/anneschuth/mattermost-claude-code.git
47
- cd mattermost-claude-code
48
- npm install
49
- npm run build
50
- npm link
58
+ cd /your/project
59
+ mm-claude
60
+ ```
61
+
62
+ On first run, an interactive setup wizard guides you through configuration:
63
+
51
64
  ```
65
+ Welcome to mm-claude!
52
66
 
53
- ## Configuration
67
+ No configuration found. Let's set things up.
54
68
 
55
- Create a config file at `~/.config/mm-claude/.env`:
69
+ You'll need:
70
+ • A Mattermost bot account with a token
71
+ • A channel ID where the bot will listen
56
72
 
57
- ```bash
58
- mkdir -p ~/.config/mm-claude
59
- cp .env.example ~/.config/mm-claude/.env
73
+ ? Mattermost URL: https://your-mattermost.com
74
+ ? Bot token: ********
75
+ ? Channel ID: abc123def456
76
+ ? Bot mention name: claude-code
77
+ ? Allowed usernames: alice,bob
78
+ ? Skip permission prompts? No
79
+
80
+ ✓ Configuration saved!
81
+ ~/.config/mm-claude/.env
82
+
83
+ Starting mm-claude...
60
84
  ```
61
85
 
62
- Edit the config with your Mattermost details:
63
- ```env
64
- MATTERMOST_URL=https://your-mattermost.com
65
- MATTERMOST_TOKEN=your-bot-token
66
- MATTERMOST_CHANNEL_ID=your-channel-id
67
- MATTERMOST_BOT_NAME=claude-code
86
+ ### 3. Use
68
87
 
69
- ALLOWED_USERS=anne.schuth,colleague1
88
+ In Mattermost, mention the bot:
70
89
 
71
- DEFAULT_WORKING_DIR=/path/to/your/project
72
- ```
90
+ ```
91
+ @claude-code help me fix the bug in src/auth.ts
92
+ ```
73
93
 
74
- ## Running
94
+ ## CLI Options
75
95
 
76
- Navigate to your project directory and run:
77
96
  ```bash
78
- cd /your/project
79
- mm-claude
97
+ mm-claude [options]
98
+
99
+ Options:
100
+ --url <url> Mattermost server URL
101
+ --token <token> Bot token
102
+ --channel <id> Channel ID
103
+ --bot-name <name> Bot mention name (default: claude-code)
104
+ --allowed-users <list> Comma-separated allowed usernames
105
+ --skip-permissions Skip permission prompts (auto-approve)
106
+ --no-skip-permissions Enable permission prompts (override env)
107
+ --debug Enable debug logging
108
+ --version Show version
109
+ --help Show help
80
110
  ```
81
111
 
82
- With debug output:
83
- ```bash
84
- mm-claude --debug
112
+ CLI options override environment variables.
113
+
114
+ ## Session Collaboration
115
+
116
+ ### Invite Users
117
+
118
+ Session owners can temporarily allow others to participate:
119
+
120
+ ```
121
+ /invite @colleague
85
122
  ```
86
123
 
87
- ## Usage
124
+ The colleague can now send messages in this session thread.
125
+
126
+ ### Kick Users
88
127
 
89
- In your Mattermost channel, mention the bot to start a session:
128
+ Remove an invited user from the session:
90
129
 
91
130
  ```
92
- @claude-code help me fix the bug in src/auth.ts
131
+ /kick @colleague
93
132
  ```
94
133
 
95
- The bot will:
96
- 1. Post a session start message
97
- 2. Stream Claude Code's responses in real-time
98
- 3. Show tool activity (file reads, edits, bash commands)
99
- 4. Post a session end message when complete
134
+ ### Message Approval
135
+
136
+ When an unauthorized user sends a message in a session thread, the owner sees an approval prompt:
137
+
138
+ ```
139
+ 🔒 @unauthorized-user wants to send a message:
140
+ > Can you also add error handling?
141
+
142
+ React 👍 to allow this message, ✅ to invite them to the session, 👎 to deny
143
+ ```
144
+
145
+ ### Side Conversations
146
+
147
+ Messages starting with `@someone-else` are ignored by the bot, allowing side conversations in the thread without triggering Claude.
100
148
 
101
149
  ## Interactive Features
102
150
 
103
- ### Typing Indicator
104
- While Claude is thinking or working, you'll see the "is typing..." indicator in Mattermost.
105
-
106
- ### Plan Mode Approval
107
- When Claude enters plan mode and is ready to implement:
108
- - Bot posts an approval message with 👍/👎 reactions
109
- - React with 👍 to approve and start building
110
- - React with 👎 to request changes
111
- - Once approved, subsequent plan exits auto-continue
112
-
113
- ### Questions with Emoji Reactions
114
- When Claude needs to ask questions:
115
- - Questions are posted one at a time (sequential flow)
116
- - Each question shows numbered options: 1️⃣ 2️⃣ 3️⃣ 4️⃣
117
- - React with the corresponding emoji to answer
118
- - After all questions are answered, Claude continues
119
-
120
- ### Task List Display
121
- When Claude creates a todo list (TodoWrite):
122
- - Tasks are shown with status icons: ⬜ pending, 🔄 in progress, ✅ completed
123
- - The task list updates in place as Claude works
124
- - In-progress tasks show the active description
125
-
126
- ### Subagent Status
127
- When Claude spawns subagents (Task tool):
128
- - Shows subagent type and description
129
- - Updates to ✅ completed when done
130
-
131
- ### Permission Approval via Reactions
132
- By default, Claude Code requests permission before executing tools. This service forwards these requests to Mattermost:
133
- - Permission requests are posted with 👍/✅/👎 reactions
134
- - 👍 **Allow this** - approve this specific tool use
135
- - ✅ **Allow all** - approve all future tool uses in this session
136
- - 👎 **Deny** - reject this tool use
137
-
138
- To skip permission prompts (use with caution):
139
- ```bash
140
- mm-claude --dangerously-skip-permissions
141
- # or set in .env:
142
- SKIP_PERMISSIONS=true
151
+ ### Permission Approval
152
+
153
+ When Claude wants to execute a tool (edit file, run command, etc.):
154
+
155
+ - **👍 Allow** - Approve this specific action
156
+ - **✅ Allow all** - Approve all future actions this session
157
+ - **👎 Deny** - Reject this action
158
+
159
+ To skip prompts: `mm-claude --skip-permissions` or set `SKIP_PERMISSIONS=true`
160
+
161
+ ### Plan Mode
162
+
163
+ When Claude creates a plan and is ready to implement:
164
+
165
+ - **👍** Approve and start building
166
+ - **👎** Request changes
167
+
168
+ Once approved, subsequent plans auto-continue.
169
+
170
+ ### Questions
171
+
172
+ When Claude asks questions with multiple choice options:
173
+
174
+ - React with 1️⃣ 2️⃣ 3️⃣ or 4️⃣ to answer
175
+ - Questions are asked one at a time
176
+
177
+ ### Task List
178
+
179
+ Claude's todo list shows live in Mattermost:
180
+
181
+ - ⬜ Pending
182
+ - 🔄 In progress
183
+ - ✅ Completed
184
+
185
+ ### Session Header
186
+
187
+ The session start message shows current status and updates when participants change:
188
+
189
+ ```
190
+ 🤖 mm-claude v0.5.1
191
+
192
+ | | |
193
+ |:--|:--|
194
+ | 📂 Directory | ~/project |
195
+ | 👤 Started by | @alice |
196
+ | 👥 Participants | @bob, @carol |
197
+ | 🔢 Session | #1 of 5 max |
198
+ | 🔐 Permissions | Interactive |
143
199
  ```
144
200
 
145
- ### Code Diffs and Previews
146
- - **Edit**: Shows actual diff with `-` old lines and `+` new lines
147
- - **Write**: Shows first 6 lines of content with line count
148
- - **Bash**: Shows the command being executed
149
- - **Read**: Shows the file path being read
150
- - **MCP tools**: Shows tool name and server (e.g., `🔌 get-library-docs *(context7)*`)
201
+ ### Cancel Session
151
202
 
152
- ## Access Control
203
+ Stop a running session:
153
204
 
154
- - **ALLOWED_USERS**: Comma-separated list of Mattermost usernames that can trigger Claude Code
155
- - If empty, anyone in the channel can use the bot (be careful!)
156
- - Non-authorized users get a polite rejection message
205
+ - Type `/stop` or `/cancel` in the thread
206
+ - React with ❌ or 🛑 to any message in the thread
157
207
 
158
- ## Message to your Mattermost admin
208
+ ## Access Control
159
209
 
160
- > "Kun je een bot account voor me aanmaken om Claude Code sessies te delen in een publiek kanaal?
161
- > Ik heb nodig: een bot account met posting rechten, een personal access token, en de bot toegevoegd aan [kanaal naam]."
210
+ Set `ALLOWED_USERS` to restrict who can use the bot:
162
211
 
163
- Or in English:
212
+ ```env
213
+ ALLOWED_USERS=alice,bob,carol
214
+ ```
164
215
 
165
- > "Could you create a bot account for me to share Claude Code sessions in a public channel?
166
- > I need: bot account with posting permissions, a personal access token, and the bot added to [channel name]."
216
+ - Only listed users can start sessions
217
+ - Only listed users can approve permissions
218
+ - Session owners can `/invite` others temporarily
219
+ - Empty = anyone can use (be careful!)
220
+
221
+ ## Environment Variables
222
+
223
+ | Variable | Description |
224
+ |----------|-------------|
225
+ | `MATTERMOST_URL` | Server URL |
226
+ | `MATTERMOST_TOKEN` | Bot token |
227
+ | `MATTERMOST_CHANNEL_ID` | Channel to listen in |
228
+ | `MATTERMOST_BOT_NAME` | Mention name (default: `claude-code`) |
229
+ | `ALLOWED_USERS` | Comma-separated usernames |
230
+ | `SKIP_PERMISSIONS` | `true` to auto-approve actions |
231
+ | `MAX_SESSIONS` | Max concurrent sessions (default: `5`) |
232
+ | `SESSION_TIMEOUT_MS` | Idle timeout in ms (default: `1800000` = 30 min) |
233
+
234
+ Config file locations (in priority order):
235
+ 1. `./.env` (current directory)
236
+ 2. `~/.config/mm-claude/.env`
237
+ 3. `~/.mm-claude.env`
238
+
239
+ ## Code Display
240
+
241
+ - **Edit**: Shows diff with `-` removed and `+` added lines
242
+ - **Write**: Shows preview of new file content
243
+ - **Bash**: Shows command being executed
244
+ - **Read**: Shows file path being read
245
+ - **MCP tools**: Shows tool name and server
246
+
247
+ ## For Mattermost Admins
248
+
249
+ To set up a bot account:
250
+
251
+ 1. Go to **Integrations > Bot Accounts > Add Bot Account**
252
+ 2. Give it a username (e.g., `claude-code`) and display name
253
+ 3. Create a **Personal Access Token** for the bot
254
+ 4. Add the bot to the channel where it should listen
255
+
256
+ The bot needs permissions to:
257
+ - Post messages
258
+ - Add reactions
259
+ - Read channel messages
167
260
 
168
261
  ## License
169
262
 
package/dist/config.js CHANGED
@@ -46,10 +46,17 @@ export function loadConfig(cliArgs) {
46
46
  .split(',')
47
47
  .map(u => u.trim())
48
48
  .filter(u => u.length > 0);
49
- // CLI --skip-permissions, env SKIP_PERMISSIONS=true, or legacy flag
50
- const skipPermissions = cliArgs?.skipPermissions ||
51
- process.env.SKIP_PERMISSIONS === 'true' ||
52
- process.argv.includes('--dangerously-skip-permissions');
49
+ // CLI --skip-permissions or --no-skip-permissions takes priority
50
+ // Then env SKIP_PERMISSIONS, then legacy flag
51
+ let skipPermissions;
52
+ if (cliArgs?.skipPermissions !== undefined) {
53
+ // CLI explicitly set (--skip-permissions or --no-skip-permissions)
54
+ skipPermissions = cliArgs.skipPermissions;
55
+ }
56
+ else {
57
+ skipPermissions = process.env.SKIP_PERMISSIONS === 'true' ||
58
+ process.argv.includes('--dangerously-skip-permissions');
59
+ }
53
60
  return {
54
61
  mattermost: {
55
62
  url: url.replace(/\/$/, ''), // Remove trailing slash
package/dist/index.js CHANGED
@@ -23,6 +23,7 @@ program
23
23
  .option('--bot-name <name>', 'Bot mention name (default: claude-code)')
24
24
  .option('--allowed-users <users>', 'Comma-separated allowed usernames')
25
25
  .option('--skip-permissions', 'Skip interactive permission prompts')
26
+ .option('--no-skip-permissions', 'Enable interactive permission prompts (override env)')
26
27
  .option('--debug', 'Enable debug logging')
27
28
  .parse();
28
29
  const opts = program.opts();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mattermost-claude-code",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "Share Claude Code sessions live in a Mattermost channel with interactive features",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",