claude-threads 0.12.0

package/README.md

@@ -0,0 +1,303 @@
+# Mattermost Claude Code Bridge
+
+[![npm version](https://img.shields.io/npm/v/claude-threads.svg)](https://www.npmjs.com/package/claude-threads)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```mermaid
+flowchart TB
+    subgraph local["Your Local Machine"]
+        cli["Claude Code CLI<br/>(subprocess)"]
+        mm["claude-threads<br/>(this service)"]
+        cli <-->|"stdio"| mm
+    end
+
+    subgraph server["Mattermost Server"]
+        bot["Bot Account<br/>@claude-code"]
+        channel["Channel<br/>#claude-sessions"]
+        bot <--> channel
+    end
+
+    mm -->|"WebSocket + REST API<br/>(outbound only)"| server
+```
+
+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 a personal access token
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g claude-threads
+```
+
+### 2. Run
+
+```bash
+cd /your/project
+claude-threads
+```
+
+On first run, an interactive setup wizard guides you through configuration:
+
+```
+Welcome to claude-threads!
+
+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/claude-threads/.env
+
+Starting claude-threads...
+```
+
+### 3. Use
+
+In Mattermost, mention the bot:
+
+```
+@claude-code help me fix the bug in src/auth.ts
+```
+
+## CLI Options
+
+```bash
+claude-threads [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
+```
+
+CLI options override environment variables.
+
+## Session Commands
+
+Type `!help` in any session thread to see available commands:
+
+| Command | Description |
+|:--------|:------------|
+| `!help` | Show available commands |
+| `!release-notes` | Show release notes for current version |
+| `!cd <path>` | Change working directory (restarts Claude) |
+| `!invite @user` | Invite a user to this session |
+| `!kick @user` | Remove an invited user |
+| `!permissions interactive` | Enable interactive permissions |
+| `!stop` | Stop this session |
+
+> **Note:** Commands use `!` prefix instead of `/` to avoid conflicts with Mattermost's slash commands.
+
+## Session Collaboration
+
+### Invite Users
+
+Session owners can temporarily allow others to participate:
+
+```
+!invite @colleague
+```
+
+The colleague can now send messages in this session thread.
+
+### Kick Users
+
+Remove an invited user from the session:
+
+```
+!kick @colleague
+```
+
+### 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
+
+### 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: `claude-threads --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:
+
+```
+🤖 claude-threads v0.5.1
+
+| | |
+|:--|:--|
+| 📂 Directory | ~/project |
+| 👤 Started by | @alice |
+| 👥 Participants | @bob, @carol |
+| 🔢 Session | #1 of 5 max |
+| 🔐 Permissions | Interactive |
+```
+
+### Cancel Session
+
+Stop a running session:
+
+- Type `!stop` or `!cancel` in the thread
+- React with ❌ or 🛑 to any message in the thread
+
+## Access Control
+
+Set `ALLOWED_USERS` to restrict who can use the bot:
+
+```env
+ALLOWED_USERS=alice,bob,carol
+```
+
+- 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) |
+| `NO_UPDATE_NOTIFIER` | Set to `1` to disable update checks |
+
+Config file locations (in priority order):
+1. `./.env` (current directory)
+2. `~/.config/claude-threads/.env`
+3. `~/.claude-threads.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
+
+## Auto-Updates
+
+claude-threads checks for updates every 30 minutes and notifies you when a new version is available:
+
+- **CLI**: Shows a notification box on startup
+- **Mattermost**: Shows a warning in session headers
+
+To update:
+
+```bash
+npm install -g claude-threads
+```
+
+To disable update checks, set `NO_UPDATE_NOTIFIER=1`.
+
+## 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
+
+MIT

package/dist/changelog.d.ts

@@ -0,0 +1,20 @@
+interface ReleaseNotes {
+    version: string;
+    date: string;
+    sections: {
+        [key: string]: string[];
+    };
+}
+/**
+ * Parse CHANGELOG.md and extract release notes for a specific version.
+ */
+export declare function getReleaseNotes(version?: string): ReleaseNotes | null;
+/**
+ * Format release notes as a Mattermost message.
+ */
+export declare function formatReleaseNotes(notes: ReleaseNotes): string;
+/**
+ * Get a short summary of what's new (for session header).
+ */
+export declare function getWhatsNewSummary(notes: ReleaseNotes): string;
+export {};

package/dist/changelog.js

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Parse CHANGELOG.md and extract release notes for a specific version.
+ */
+export function getReleaseNotes(version) {
+    // Try to find CHANGELOG.md in various locations
+    const possiblePaths = [
+        resolve(__dirname, '..', 'CHANGELOG.md'), // dist/../CHANGELOG.md (installed)
+        resolve(__dirname, '..', '..', 'CHANGELOG.md'), // src/../CHANGELOG.md (dev)
+    ];
+    let changelogPath = null;
+    for (const p of possiblePaths) {
+        if (existsSync(p)) {
+            changelogPath = p;
+            break;
+        }
+    }
+    if (!changelogPath) {
+        return null;
+    }
+    try {
+        const content = readFileSync(changelogPath, 'utf-8');
+        return parseChangelog(content, version);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse changelog content and extract notes for a version.
+ * If no version specified, returns the latest (first) version.
+ */
+function parseChangelog(content, targetVersion) {
+    const lines = content.split('\n');
+    let currentVersion = null;
+    let currentDate = null;
+    let currentSection = null;
+    let sections = {};
+    let foundTarget = false;
+    for (const line of lines) {
+        // Match version header: ## [0.8.0] - 2025-12-28
+        const versionMatch = line.match(/^## \[(\d+\.\d+\.\d+)\](?: - (\d{4}-\d{2}-\d{2}))?/);
+        if (versionMatch) {
+            // If we already found our target, we're done
+            if (foundTarget) {
+                break;
+            }
+            currentVersion = versionMatch[1];
+            currentDate = versionMatch[2] || '';
+            sections = {};
+            currentSection = null;
+            // Check if this is the version we want
+            if (!targetVersion || currentVersion === targetVersion) {
+                foundTarget = true;
+            }
+            continue;
+        }
+        // Only process if we're in the target version
+        if (!foundTarget)
+            continue;
+        // Match section header: ### Added, ### Fixed, ### Changed
+        const sectionMatch = line.match(/^### (\w+)/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1];
+            sections[currentSection] = [];
+            continue;
+        }
+        // Match list item: - Item text
+        const itemMatch = line.match(/^- (.+)/);
+        if (itemMatch && currentSection) {
+            sections[currentSection].push(itemMatch[1]);
+        }
+    }
+    if (!foundTarget || !currentVersion) {
+        return null;
+    }
+    return {
+        version: currentVersion,
+        date: currentDate || '',
+        sections,
+    };
+}
+/**
+ * Format release notes as a Mattermost message.
+ */
+export function formatReleaseNotes(notes) {
+    let msg = `### 📋 Release Notes - v${notes.version}`;
+    if (notes.date) {
+        msg += ` (${notes.date})`;
+    }
+    msg += '\n\n';
+    for (const [section, items] of Object.entries(notes.sections)) {
+        if (items.length === 0)
+            continue;
+        const emoji = section === 'Added' ? '✨' :
+            section === 'Fixed' ? '🐛' :
+                section === 'Changed' ? '🔄' :
+                    section === 'Removed' ? '🗑️' : '•';
+        msg += `**${emoji} ${section}**\n`;
+        for (const item of items) {
+            msg += `- ${item}\n`;
+        }
+        msg += '\n';
+    }
+    return msg.trim();
+}
+/**
+ * Get a short summary of what's new (for session header).
+ */
+export function getWhatsNewSummary(notes) {
+    const items = [];
+    // Prioritize: Added > Fixed > Changed
+    for (const section of ['Added', 'Fixed', 'Changed']) {
+        const sectionItems = notes.sections[section] || [];
+        for (const item of sectionItems) {
+            // Extract just the first part (before any dash or detail)
+            const short = item.split(' - ')[0].replace(/\*\*/g, '');
+            if (short.length <= 50) {
+                items.push(short);
+            }
+            else {
+                items.push(short.substring(0, 47) + '...');
+            }
+            if (items.length >= 2)
+                break;
+        }
+        if (items.length >= 2)
+            break;
+    }
+    return items.join(', ');
+}

package/dist/claude/cli.d.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from 'events';
+export interface ClaudeEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface TextContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface ImageContentBlock {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+}
+export type ContentBlock = TextContentBlock | ImageContentBlock;
+export interface ClaudeCliOptions {
+    workingDir: string;
+    threadId?: string;
+    skipPermissions?: boolean;
+    sessionId?: string;
+    resume?: boolean;
+    chrome?: boolean;
+}
+export declare class ClaudeCli extends EventEmitter {
+    private process;
+    private options;
+    private buffer;
+    debug: boolean;
+    constructor(options: ClaudeCliOptions);
+    start(): void;
+    sendMessage(content: string | ContentBlock[]): void;
+    sendToolResult(toolUseId: string, content: unknown): void;
+    private parseOutput;
+    isRunning(): boolean;
+    kill(): void;
+    /** Interrupt current processing (like Escape in CLI) - keeps process alive */
+    interrupt(): boolean;
+    private getMcpServerPath;
+}

package/dist/claude/cli.js

@@ -0,0 +1,173 @@
+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',
+        ];
+        // Add session ID for persistence/resume support
+        if (this.options.sessionId) {
+            if (this.options.resume) {
+                args.push('--resume', this.options.sessionId);
+            }
+            else {
+                args.push('--session-id', this.options.sessionId);
+            }
+        }
+        // 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: {
+                    'claude-threads-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__claude-threads-permissions__permission_prompt');
+        }
+        // Chrome integration
+        if (this.options.chrome) {
+            args.push('--chrome');
+        }
+        if (this.debug) {
+            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) => {
+            if (this.debug) {
+                console.error(`  [claude:err] ${chunk.toString().trim()}`);
+            }
+        });
+        this.process.on('error', (err) => {
+            console.error('  ❌ Claude error:', err);
+            this.emit('error', err);
+        });
+        this.process.on('exit', (code) => {
+            if (this.debug) {
+                console.log(`  [claude] Exited ${code}`);
+            }
+            this.process = null;
+            this.buffer = '';
+            this.emit('exit', code);
+        });
+    }
+    // Send a user message via JSON stdin
+    // content can be a string or an array of content blocks (for images)
+    sendMessage(content) {
+        if (!this.process?.stdin)
+            throw new Error('Not running');
+        const msg = JSON.stringify({
+            type: 'user',
+            message: { role: 'user', content }
+        }) + '\n';
+        if (this.debug) {
+            const preview = typeof content === 'string'
+                ? content.substring(0, 50)
+                : `[${content.length} blocks]`;
+            console.log(`  [claude] Sending: ${preview}...`);
+        }
+        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';
+        if (this.debug) {
+            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;
+    }
+    /** Interrupt current processing (like Escape in CLI) - keeps process alive */
+    interrupt() {
+        if (!this.process)
+            return false;
+        this.process.kill('SIGINT');
+        return true;
+    }
+    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');
+    }
+}