mattermost-claude-code 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anne Schuth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Mattermost Claude Code Bridge
+
+[![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.
+
+## How it works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Your Local Machine                          │
+│  ┌─────────────────┐         ┌─────────────────────────────┐   │
+│  │ Claude Code CLI │◄───────►│ This service                │   │
+│  │ (subprocess)    │ stdio   │ (Node.js)                   │   │
+│  └─────────────────┘         └──────────┬──────────────────┘   │
+└─────────────────────────────────────────┼───────────────────────┘
+                                          │ WebSocket + REST API
+                                          ▼ (outbound only!)
+┌─────────────────────────────────────────────────────────────────┐
+│                     Mattermost Server                           │
+│  ┌─────────────────┐         ┌─────────────────────────────┐   │
+│  │ Bot Account     │         │ Public Channel              │   │
+│  │ @claude-code    │◄───────►│ #claude-code-sessions       │   │
+│  └─────────────────┘         └─────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+This runs entirely on your local machine - it only makes **outbound** connections to Mattermost. No port forwarding or public IP 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)
+
+## Installation
+
+### Option 1: npm (recommended)
+```bash
+npm install -g mattermost-claude-code
+```
+
+### Option 2: From source
+```bash
+git clone https://github.com/anneschuth/mattermost-claude-code.git
+cd mattermost-claude-code
+npm install
+npm run build
+npm link
+```
+
+## Configuration
+
+Create a config file at `~/.config/mm-claude/.env`:
+
+```bash
+mkdir -p ~/.config/mm-claude
+cp .env.example ~/.config/mm-claude/.env
+```
+
+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
+
+   ALLOWED_USERS=anne.schuth,colleague1
+
+   DEFAULT_WORKING_DIR=/path/to/your/project
+   ```
+
+## Running
+
+Navigate to your project directory and run:
+```bash
+cd /your/project
+mm-claude
+```
+
+With debug output:
+```bash
+mm-claude --debug
+```
+
+## Usage
+
+In your Mattermost channel, mention the bot to start a session:
+
+```
+@claude-code help me fix the bug in src/auth.ts
+```
+
+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
+
+## 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
+```
+
+### 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)*`)
+
+## Access Control
+
+- **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
+
+## Message to your Mattermost admin
+
+> "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]."
+
+Or in English:
+
+> "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]."
+
+## License
+
+MIT

package/dist/claude/cli.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from 'events';
+export interface ClaudeEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ClaudeCliOptions {
+    workingDir: string;
+    threadId?: string;
+    skipPermissions?: boolean;
+}
+export declare class ClaudeCli extends EventEmitter {
+    private process;
+    private options;
+    private buffer;
+    debug: boolean;
+    constructor(options: ClaudeCliOptions);
+    start(): void;
+    sendMessage(content: string): void;
+    sendToolResult(toolUseId: string, content: unknown): void;
+    private parseOutput;
+    isRunning(): boolean;
+    kill(): void;
+    private getMcpServerPath;
+}

package/dist/claude/cli.js

@@ -0,0 +1,139 @@
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+export class ClaudeCli extends EventEmitter {
+    process = null;
+    options;
+    buffer = '';
+    debug = process.env.DEBUG === '1' || process.argv.includes('--debug');
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    start() {
+        if (this.process)
+            throw new Error('Already running');
+        const claudePath = process.env.CLAUDE_PATH || 'claude';
+        const args = [
+            '--input-format', 'stream-json',
+            '--output-format', 'stream-json',
+            '--verbose',
+        ];
+        // Either use skip permissions or the MCP-based permission system
+        if (this.options.skipPermissions) {
+            args.push('--dangerously-skip-permissions');
+        }
+        else {
+            // Configure the permission MCP server
+            const mcpServerPath = this.getMcpServerPath();
+            const mcpConfig = {
+                mcpServers: {
+                    'mm-claude-permissions': {
+                        type: 'stdio',
+                        command: 'node',
+                        args: [mcpServerPath],
+                        env: {
+                            MM_THREAD_ID: this.options.threadId || '',
+                            MATTERMOST_URL: process.env.MATTERMOST_URL || '',
+                            MATTERMOST_TOKEN: process.env.MATTERMOST_TOKEN || '',
+                            MATTERMOST_CHANNEL_ID: process.env.MATTERMOST_CHANNEL_ID || '',
+                            ALLOWED_USERS: process.env.ALLOWED_USERS || '',
+                            DEBUG: this.debug ? '1' : '',
+                        },
+                    },
+                },
+            };
+            args.push('--mcp-config', JSON.stringify(mcpConfig));
+            args.push('--permission-prompt-tool', 'mcp__mm-claude-permissions__permission_prompt');
+        }
+        console.log(`[Claude] Starting: ${claudePath} ${args.slice(0, 5).join(' ')}...`);
+        this.process = spawn(claudePath, args, {
+            cwd: this.options.workingDir,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.process.stdout?.on('data', (chunk) => {
+            this.parseOutput(chunk.toString());
+        });
+        this.process.stderr?.on('data', (chunk) => {
+            console.error(`[Claude stderr] ${chunk.toString().trim()}`);
+        });
+        this.process.on('error', (err) => {
+            console.error('[Claude] Error:', err);
+            this.emit('error', err);
+        });
+        this.process.on('exit', (code) => {
+            console.log(`[Claude] Exited ${code}`);
+            this.process = null;
+            this.buffer = '';
+            this.emit('exit', code);
+        });
+    }
+    // Send a user message via JSON stdin
+    sendMessage(content) {
+        if (!this.process?.stdin)
+            throw new Error('Not running');
+        const msg = JSON.stringify({
+            type: 'user',
+            message: { role: 'user', content }
+        }) + '\n';
+        console.log(`[Claude] Sending: ${content.substring(0, 50)}...`);
+        this.process.stdin.write(msg);
+    }
+    // Send a tool result response
+    sendToolResult(toolUseId, content) {
+        if (!this.process?.stdin)
+            throw new Error('Not running');
+        const msg = JSON.stringify({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: [{
+                        type: 'tool_result',
+                        tool_use_id: toolUseId,
+                        content: typeof content === 'string' ? content : JSON.stringify(content)
+                    }]
+            }
+        }) + '\n';
+        console.log(`[Claude] Sending tool_result for ${toolUseId}`);
+        this.process.stdin.write(msg);
+    }
+    parseOutput(data) {
+        this.buffer += data;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() || '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const event = JSON.parse(trimmed);
+                if (this.debug) {
+                    console.log(`[DEBUG] Event: ${event.type}`, JSON.stringify(event).substring(0, 200));
+                }
+                this.emit('event', event);
+            }
+            catch {
+                if (this.debug) {
+                    console.log(`[DEBUG] Raw: ${trimmed.substring(0, 200)}`);
+                }
+            }
+        }
+    }
+    isRunning() {
+        return this.process !== null;
+    }
+    kill() {
+        this.process?.kill('SIGTERM');
+        this.process = null;
+    }
+    getMcpServerPath() {
+        // Get the path to the MCP permission server
+        // When running from source: src/mcp/permission-server.ts -> dist/mcp/permission-server.js
+        // When installed globally: the bin entry points to dist/mcp/permission-server.js
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        return resolve(__dirname, '..', 'mcp', 'permission-server.js');
+    }
+}

package/dist/claude/session.d.ts

@@ -0,0 +1,41 @@
+import { MattermostClient } from '../mattermost/client.js';
+export declare class SessionManager {
+    private claude;
+    private mattermost;
+    private workingDir;
+    private skipPermissions;
+    private session;
+    private updateTimer;
+    private typingTimer;
+    private pendingQuestionSet;
+    private pendingApproval;
+    private planApproved;
+    private tasksPostId;
+    private activeSubagents;
+    private debug;
+    constructor(mattermost: MattermostClient, workingDir: string, skipPermissions?: boolean);
+    startSession(options: {
+        prompt: string;
+    }, username: string, replyToPostId?: string): Promise<void>;
+    private handleEvent;
+    private handleTaskComplete;
+    private handleExitPlanMode;
+    private handleTodoWrite;
+    private handleTaskStart;
+    private handleAskUserQuestion;
+    private postCurrentQuestion;
+    private handleReaction;
+    private handleApprovalReaction;
+    private formatEvent;
+    private formatToolUse;
+    private appendContent;
+    private scheduleUpdate;
+    private startTyping;
+    private stopTyping;
+    private flush;
+    private handleExit;
+    isSessionActive(): boolean;
+    isInCurrentSessionThread(threadRoot: string): boolean;
+    sendFollowUp(message: string): Promise<void>;
+    killSession(): void;
+}