mattermost-claude-code 0.5.1 → 0.5.3

package/README.md

@@ -3,7 +3,17 @@
 [![npm version](https://img.shields.io/npm/v/mattermost-claude-code.svg)](https://www.npmjs.com/package/mattermost-claude-code)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-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.
+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.
+
+## Features
+
+- **Real-time streaming** - Claude's responses stream live to Mattermost
+- **Multiple concurrent sessions** - Each thread gets its own Claude session
+- **Session collaboration** - Invite others to participate in your session
+- **Interactive permissions** - Approve Claude's actions via emoji reactions
+- **Plan approval** - Review and approve Claude's plans before execution
+- **Task tracking** - Live todo list updates as Claude works
+- **Code diffs** - See exactly what Claude is changing
 
 ## How it works
 
@@ -11,159 +21,252 @@ Share your Claude Code sessions live in a public Mattermost channel. Your collea
 ┌─────────────────────────────────────────────────────────────────┐
 │                     Your Local Machine                          │
 │  ┌─────────────────┐         ┌─────────────────────────────┐   │
-│  │ Claude Code CLI │◄───────►│ This service                │   │
-│  │ (subprocess)    │ stdio   │ (Node.js)                   │   │
+│  │ Claude Code CLI │◀───────▶│ mm-claude                   │   │
+│  │ (subprocess)    │ stdio   │ (this service)              │   │
 │  └─────────────────┘         └──────────┬──────────────────┘   │
 └─────────────────────────────────────────┼───────────────────────┘
                                           │ WebSocket + REST API
-                                          ▼ (outbound only!)
+                                          ▼ (outbound only)
 ┌─────────────────────────────────────────────────────────────────┐
 │                     Mattermost Server                           │
 │  ┌─────────────────┐         ┌─────────────────────────────┐   │
-│  │ Bot Account     │         │ Public Channel              │   │
-│  │ @claude-code    │◄───────►│ #claude-code-sessions       │   │
+│  │ Bot Account     │◀───────▶│ Channel                     │   │
+│  │ @claude-code    │         │ #claude-sessions            │   │
 │  └─────────────────┘         └─────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-This runs entirely on your local machine - it only makes **outbound** connections to Mattermost. No port forwarding or public IP needed!
+Runs entirely on your machine - only **outbound** connections to Mattermost. No port forwarding needed!
 
 ## Prerequisites
 
 1. **Claude Code CLI** installed and authenticated (`claude --version`)
 2. **Node.js 18+**
-3. **Mattermost bot account** with personal access token (ask your admin)
+3. **Mattermost bot account** with a personal access token
 
-## Installation
+## Quick Start
+
+### 1. Install
 
-### Option 1: npm (recommended)
 ```bash
 npm install -g mattermost-claude-code
 ```
 
-### Option 2: From source
+### 2. Run
+
 ```bash
-git clone https://github.com/anneschuth/mattermost-claude-code.git
-cd mattermost-claude-code
-npm install
-npm run build
-npm link
+cd /your/project
+mm-claude
 ```
 
-## Configuration
+On first run, an interactive setup wizard guides you through configuration:
 
-Create a config file at `~/.config/mm-claude/.env`:
+```
+Welcome to mm-claude!
 
-```bash
-mkdir -p ~/.config/mm-claude
-cp .env.example ~/.config/mm-claude/.env
+No configuration found. Let's set things up.
+
+You'll need:
+• A Mattermost bot account with a token
+• A channel ID where the bot will listen
+
+? Mattermost URL: https://your-mattermost.com
+? Bot token: ********
+? Channel ID: abc123def456
+? Bot mention name: claude-code
+? Allowed usernames: alice,bob
+? Skip permission prompts? No
+
+✓ Configuration saved!
+  ~/.config/mm-claude/.env
+
+Starting mm-claude...
 ```
 
-Edit the config with your Mattermost details:
-   ```env
-   MATTERMOST_URL=https://your-mattermost.com
-   MATTERMOST_TOKEN=your-bot-token
-   MATTERMOST_CHANNEL_ID=your-channel-id
-   MATTERMOST_BOT_NAME=claude-code
+### 3. Use
 
-   ALLOWED_USERS=anne.schuth,colleague1
+In Mattermost, mention the bot:
 
-   DEFAULT_WORKING_DIR=/path/to/your/project
-   ```
+```
+@claude-code help me fix the bug in src/auth.ts
+```
 
-## Running
+## CLI Options
 
-Navigate to your project directory and run:
 ```bash
-cd /your/project
-mm-claude
+mm-claude [options]
+
+Options:
+  --url <url>            Mattermost server URL
+  --token <token>        Bot token
+  --channel <id>         Channel ID
+  --bot-name <name>      Bot mention name (default: claude-code)
+  --allowed-users <list> Comma-separated allowed usernames
+  --skip-permissions     Skip permission prompts (auto-approve)
+  --no-skip-permissions  Enable permission prompts (override env)
+  --debug                Enable debug logging
+  --version              Show version
+  --help                 Show help
 ```
 
-With debug output:
-```bash
-mm-claude --debug
+CLI options override environment variables.
+
+## Session Collaboration
+
+### Invite Users
+
+Session owners can temporarily allow others to participate:
+
+```
+/invite @colleague
 ```
 
-## Usage
+The colleague can now send messages in this session thread.
 
-In your Mattermost channel, mention the bot to start a session:
+### Kick Users
+
+Remove an invited user from the session:
 
 ```
-@claude-code help me fix the bug in src/auth.ts
+/kick @colleague
 ```
 
-The bot will:
-1. Post a session start message
-2. Stream Claude Code's responses in real-time
-3. Show tool activity (file reads, edits, bash commands)
-4. Post a session end message when complete
+### Message Approval
+
+When an unauthorized user sends a message in a session thread, the owner sees an approval prompt:
+
+```
+🔒 @unauthorized-user wants to send a message:
+> Can you also add error handling?
+
+React 👍 to allow this message, ✅ to invite them to the session, 👎 to deny
+```
+
+### Side Conversations
+
+Messages starting with `@someone-else` are ignored by the bot, allowing side conversations in the thread without triggering Claude.
+
+### Downgrade Permissions
+
+If the bot is running with `--skip-permissions` (auto mode), you can enable interactive permissions for a specific session:
+
+```
+/permissions interactive
+```
+
+This allows collaboration by requiring approval for Claude's actions. Note: you can only downgrade (auto → interactive), not upgrade - this ensures security.
 
 ## Interactive Features
 
-### Typing Indicator
-While Claude is thinking or working, you'll see the "is typing..." indicator in Mattermost.
-
-### Plan Mode Approval
-When Claude enters plan mode and is ready to implement:
-- Bot posts an approval message with 👍/👎 reactions
-- React with 👍 to approve and start building
-- React with 👎 to request changes
-- Once approved, subsequent plan exits auto-continue
-
-### Questions with Emoji Reactions
-When Claude needs to ask questions:
-- Questions are posted one at a time (sequential flow)
-- Each question shows numbered options: 1️⃣ 2️⃣ 3️⃣ 4️⃣
-- React with the corresponding emoji to answer
-- After all questions are answered, Claude continues
-
-### Task List Display
-When Claude creates a todo list (TodoWrite):
-- Tasks are shown with status icons: ⬜ pending, 🔄 in progress, ✅ completed
-- The task list updates in place as Claude works
-- In-progress tasks show the active description
-
-### Subagent Status
-When Claude spawns subagents (Task tool):
-- Shows subagent type and description
-- Updates to ✅ completed when done
-
-### Permission Approval via Reactions
-By default, Claude Code requests permission before executing tools. This service forwards these requests to Mattermost:
-- Permission requests are posted with 👍/✅/👎 reactions
-- 👍 **Allow this** - approve this specific tool use
-- ✅ **Allow all** - approve all future tool uses in this session
-- 👎 **Deny** - reject this tool use
-
-To skip permission prompts (use with caution):
-```bash
-mm-claude --dangerously-skip-permissions
-# or set in .env:
-SKIP_PERMISSIONS=true
+### Permission Approval
+
+When Claude wants to execute a tool (edit file, run command, etc.):
+
+- **👍 Allow** - Approve this specific action
+- **✅ Allow all** - Approve all future actions this session
+- **👎 Deny** - Reject this action
+
+To skip prompts: `mm-claude --skip-permissions` or set `SKIP_PERMISSIONS=true`
+
+### Plan Mode
+
+When Claude creates a plan and is ready to implement:
+
+- **👍** Approve and start building
+- **👎** Request changes
+
+Once approved, subsequent plans auto-continue.
+
+### Questions
+
+When Claude asks questions with multiple choice options:
+
+- React with 1️⃣ 2️⃣ 3️⃣ or 4️⃣ to answer
+- Questions are asked one at a time
+
+### Task List
+
+Claude's todo list shows live in Mattermost:
+
+- ⬜ Pending
+- 🔄 In progress
+- ✅ Completed
+
+### Session Header
+
+The session start message shows current status and updates when participants change:
+
+```
+🤖 mm-claude v0.5.1
+
+| | |
+|:--|:--|
+| 📂 Directory | ~/project |
+| 👤 Started by | @alice |
+| 👥 Participants | @bob, @carol |
+| 🔢 Session | #1 of 5 max |
+| 🔐 Permissions | Interactive |
 ```
 
-### Code Diffs and Previews
-- **Edit**: Shows actual diff with `-` old lines and `+` new lines
-- **Write**: Shows first 6 lines of content with line count
-- **Bash**: Shows the command being executed
-- **Read**: Shows the file path being read
-- **MCP tools**: Shows tool name and server (e.g., `🔌 get-library-docs *(context7)*`)
+### Cancel Session
 
-## Access Control
+Stop a running session:
 
-- **ALLOWED_USERS**: Comma-separated list of Mattermost usernames that can trigger Claude Code
-- If empty, anyone in the channel can use the bot (be careful!)
-- Non-authorized users get a polite rejection message
+- Type `/stop` or `/cancel` in the thread
+- React with ❌ or 🛑 to any message in the thread
 
-## Message to your Mattermost admin
+## Access Control
 
-> "Kun je een bot account voor me aanmaken om Claude Code sessies te delen in een publiek kanaal?
-> Ik heb nodig: een bot account met posting rechten, een personal access token, en de bot toegevoegd aan [kanaal naam]."
+Set `ALLOWED_USERS` to restrict who can use the bot:
 
-Or in English:
+```env
+ALLOWED_USERS=alice,bob,carol
+```
 
-> "Could you create a bot account for me to share Claude Code sessions in a public channel?
-> I need: bot account with posting permissions, a personal access token, and the bot added to [channel name]."
+- Only listed users can start sessions
+- Only listed users can approve permissions
+- Session owners can `/invite` others temporarily
+- Empty = anyone can use (be careful!)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MATTERMOST_URL` | Server URL |
+| `MATTERMOST_TOKEN` | Bot token |
+| `MATTERMOST_CHANNEL_ID` | Channel to listen in |
+| `MATTERMOST_BOT_NAME` | Mention name (default: `claude-code`) |
+| `ALLOWED_USERS` | Comma-separated usernames |
+| `SKIP_PERMISSIONS` | `true` to auto-approve actions |
+| `MAX_SESSIONS` | Max concurrent sessions (default: `5`) |
+| `SESSION_TIMEOUT_MS` | Idle timeout in ms (default: `1800000` = 30 min) |
+
+Config file locations (in priority order):
+1. `./.env` (current directory)
+2. `~/.config/mm-claude/.env`
+3. `~/.mm-claude.env`
+
+## Code Display
+
+- **Edit**: Shows diff with `-` removed and `+` added lines
+- **Write**: Shows preview of new file content
+- **Bash**: Shows command being executed
+- **Read**: Shows file path being read
+- **MCP tools**: Shows tool name and server
+
+## For Mattermost Admins
+
+To set up a bot account:
+
+1. Go to **Integrations > Bot Accounts > Add Bot Account**
+2. Give it a username (e.g., `claude-code`) and display name
+3. Create a **Personal Access Token** for the bot
+4. Add the bot to the channel where it should listen
+
+The bot needs permissions to:
+- Post messages
+- Add reactions
+- Read channel messages
 
 ## License
 

package/dist/claude/session.d.ts

@@ -45,6 +45,7 @@ interface Session {
     pendingMessageApproval: PendingMessageApproval | null;
     planApproved: boolean;
     sessionAllowedUsers: Set<string>;
+    forceInteractivePermissions: boolean;
     sessionStartPostId: string | null;
     tasksPostId: string | null;
     activeSubagents: Map<string, string>;
@@ -111,6 +112,13 @@ export declare class SessionManager {
     inviteUser(threadId: string, invitedUser: string, invitedBy: string): Promise<void>;
     /** Kick a user from a specific session */
     kickUser(threadId: string, kickedUser: string, kickedBy: string): Promise<void>;
+    /**
+     * Enable interactive permissions for a session.
+     * Can only downgrade (skip → interactive), not upgrade.
+     */
+    enableInteractivePermissions(threadId: string, username: string): Promise<void>;
+    /** Check if a session should use interactive permissions */
+    isSessionInteractive(threadId: string): boolean;
     /** Update the session header post with current participants */
     private updateSessionHeader;
     /** Request approval for a message from an unauthorized user */

package/dist/claude/session.js

@@ -121,6 +121,7 @@ export class SessionManager {
             pendingMessageApproval: null,
             planApproved: false,
             sessionAllowedUsers: new Set([username]), // Owner is always allowed
+            forceInteractivePermissions: false, // Can be enabled via /permissions interactive
             sessionStartPostId: post.id, // Track for updating participants
             tasksPostId: null,
             activeSubagents: new Map(),
@@ -813,12 +814,53 @@ export class SessionManager {
             await this.mattermost.createPost(`⚠️ @${kickedUser} was not in this session`, threadId);
         }
     }
+    /**
+     * Enable interactive permissions for a session.
+     * Can only downgrade (skip → interactive), not upgrade.
+     */
+    async enableInteractivePermissions(threadId, username) {
+        const session = this.sessions.get(threadId);
+        if (!session)
+            return;
+        // Only session owner or globally allowed users can change permissions
+        if (session.startedBy !== username && !this.mattermost.isUserAllowed(username)) {
+            await this.mattermost.createPost(`⚠️ Only @${session.startedBy} or allowed users can change permissions`, threadId);
+            return;
+        }
+        // Can only downgrade, not upgrade
+        if (!this.skipPermissions) {
+            await this.mattermost.createPost(`ℹ️ Permissions are already interactive for this session`, threadId);
+            return;
+        }
+        // Already enabled for this session
+        if (session.forceInteractivePermissions) {
+            await this.mattermost.createPost(`ℹ️ Interactive permissions already enabled for this session`, threadId);
+            return;
+        }
+        session.forceInteractivePermissions = true;
+        await this.mattermost.createPost(`🔐 Interactive permissions enabled for this session by @${username}`, threadId);
+        console.log(`  🔐 Interactive permissions enabled for session by @${username}`);
+        await this.updateSessionHeader(session);
+    }
+    /** Check if a session should use interactive permissions */
+    isSessionInteractive(threadId) {
+        const session = this.sessions.get(threadId);
+        if (!session)
+            return !this.skipPermissions;
+        // If global is interactive, always interactive
+        if (!this.skipPermissions)
+            return true;
+        // If session has forced interactive, use that
+        return session.forceInteractivePermissions;
+    }
     /** Update the session header post with current participants */
     async updateSessionHeader(session) {
         if (!session.sessionStartPostId)
             return;
         const shortDir = this.workingDir.replace(process.env.HOME || '', '~');
-        const permMode = this.skipPermissions ? '⚡ Auto' : '🔐 Interactive';
+        // Check session-level permission override
+        const isInteractive = !this.skipPermissions || session.forceInteractivePermissions;
+        const permMode = isInteractive ? '🔐 Interactive' : '⚡ Auto';
         // Build participants list (excluding owner who is shown in "Started by")
         const otherParticipants = [...session.sessionAllowedUsers]
             .filter(u => u !== session.startedBy)

package/dist/index.js

@@ -102,6 +102,19 @@ async function main() {
                 await session.kickUser(threadRoot, kickMatch[1], username);
                 return;
             }
+            // Check for /permissions command
+            const permMatch = content.match(/^\/permissions?\s+(interactive|auto)/i);
+            if (permMatch) {
+                const mode = permMatch[1].toLowerCase();
+                if (mode === 'interactive') {
+                    await session.enableInteractivePermissions(threadRoot, username);
+                }
+                else {
+                    // Can't upgrade to auto - that would be less secure
+                    await mattermost.createPost(`⚠️ Cannot upgrade to auto permissions - can only downgrade to interactive`, threadRoot);
+                }
+                return;
+            }
             // Check if user is allowed in this session
             if (!session.isUserAllowedInSession(threadRoot, username)) {
                 // Request approval for their message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mattermost-claude-code",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Share Claude Code sessions live in a Mattermost channel with interactive features",
   "main": "dist/index.js",
   "type": "module",