claude-threads 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2025-12-30
+
+### Added
+- **Multi-platform architecture** - Foundation for supporting multiple chat platforms
+  - New `PlatformClient` interface abstracts platform differences
+  - Normalized types: `PlatformPost`, `PlatformUser`, `PlatformReaction`, `PlatformFile`
+  - Mattermost implementation moved to `src/platform/mattermost/`
+  - Slack support architecture ready (implementation pending)
+- **YAML-based configuration** - New config format
+  - Config file: `~/.config/claude-threads/config.yaml`
+  - Support for multiple platform instances simultaneously
+  - Interactive onboarding wizard creates YAML config
+
+### Changed
+- **Modular session management** - Broke 2,500-line monolith into focused modules
+  - `session/manager.ts` (~635 lines) - Thin orchestrator
+  - `session/lifecycle.ts` (~590 lines) - Session start/resume/exit
+  - `session/events.ts` (~480 lines) - Claude CLI event handling
+  - `session/commands.ts` (~510 lines) - User commands
+  - `session/reactions.ts` (~210 lines) - Emoji reaction handling
+  - `session/worktree.ts` (~520 lines) - Git worktree management
+  - `session/streaming.ts` (~180 lines) - Message batching
+  - Uses dependency injection for testability
+- **Platform-agnostic utilities** - Moved emoji helpers to `src/utils/emoji.ts`
+- **Cleaner logo exports** - Renamed to generic `getLogo()`, `LOGO`, `LOGO_INLINE`
+
+### Removed
+- **Legacy `.env` configuration** - Now uses YAML only (`config.yaml`)
+- **`dotenv` dependency** - No longer needed
+- Deprecated Mattermost-specific exports (`getMattermostLogo`, `MATTERMOST_LOGO`)
+- Internal documentation files (moved to CLAUDE.md)
+
+## [0.13.0] - 2025-12-29
+
+### Added
+- **`--setup` flag** - Re-run interactive setup wizard to reconfigure settings
+  - Existing .env values are used as defaults (press Enter to keep)
+  - Token field allows keeping existing token without re-entering
+  - New settings added since initial setup are presented with built-in defaults
+  - Config saved back to original location
+- **Chrome and worktree settings in onboarding** - New setup prompts for:
+  - Chrome integration (yes/no)
+  - Git worktree mode (prompt/off/require)
+
+### Changed
+- **Improved README** - New tagline and improved intro section
+- **Worktree documentation** - Added comprehensive Git Worktrees section to README
+- **Updated CLI options** - Added `--chrome`, `--no-chrome`, `--worktree-mode`, `--setup` to README
+
+### Fixed
+- **Warning icon alignment** - Fixed spacing of ⚠️ icon in CLI startup output
+- **WORKTREE_MODE documentation** - Fixed incorrect values in README (was `always`/`never`, now correctly `off`/`prompt`/`require`)
+
 ## [0.12.1] - 2025-12-29
 
 ### Fixed

package/README.md

@@ -9,7 +9,9 @@
 [![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.
+**Bring Claude Code to your team.** Run Claude Code on your machine, share it live in Mattermost. Colleagues can watch, collaborate, and run their own sessions—all from chat.
+
+> 💡 *Think of it as screen-sharing for AI pair programming, but everyone can type.*
 
 ## Features
 
@@ -66,25 +68,41 @@ claude-threads
 On first run, an interactive setup wizard guides you through configuration:
 
 ```
-Welcome to claude-threads!
+  claude-threads setup
+  ─────────────────────────────────
+
+  Welcome! Let's configure claude-threads.
+
+? Default working directory: /home/user/projects
+? Enable Chrome integration? No
+? Git worktree mode: Prompt
 
-No configuration found. Let's set things up.
+  Now let's add your platform connections.
 
-You'll need:
-• A Mattermost bot account with a token
-• A channel ID where the bot will listen
+? First platform: Mattermost
+? Platform ID: default
+? Display name: Mattermost
 
-? Mattermost URL: https://your-mattermost.com
+  Mattermost setup:
+
+? Server URL: https://chat.example.com
 ? Bot token: ********
 ? Channel ID: abc123def456
 ? Bot mention name: claude-code
-? Allowed usernames: alice,bob
-? Skip permission prompts? No
+? Allowed usernames (optional): alice,bob
+? Auto-approve all actions? No
+
+  ✓ Added Mattermost
 
-✓ Configuration saved!
-  ~/.config/claude-threads/.env
+? Add another platform? No
 
-Starting claude-threads...
+  ✓ Configuration saved!
+    ~/.config/claude-threads/config.yaml
+
+  Configured 1 platform(s):
+    • Mattermost (mattermost)
+
+  Starting claude-threads...
 ```
 
 ### 3. Use
@@ -101,16 +119,20 @@ In Mattermost, mention the bot:
 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
+  --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)
+  --chrome                 Enable Chrome integration
+  --no-chrome              Disable Chrome integration
+  --worktree-mode <mode>   Git worktree mode: off, prompt, require
+  --setup                  Re-run setup wizard (reconfigure settings)
+  --debug                  Enable debug logging
+  --version                Show version
+  --help                   Show help
 ```
 
 CLI options override environment variables.
@@ -123,11 +145,17 @@ Type `!help` in any session thread to see available commands:
 |:--------|:------------|
 | `!help` | Show available commands |
 | `!release-notes` | Show release notes for current version |
+| `!context` | Show context usage (tokens used/remaining) |
+| `!cost` | Show token usage and cost for this session |
+| `!compact` | Compress context to free up space |
 | `!cd <path>` | Change working directory (restarts Claude) |
+| `!worktree <branch>` | Create and switch to a git worktree |
 | `!invite @user` | Invite a user to this session |
 | `!kick @user` | Remove an invited user |
 | `!permissions interactive` | Enable interactive permissions |
+| `!escape` | Interrupt current task (keeps session active) |
 | `!stop` | Stop this session |
+| `!kill` | Emergency shutdown (kills ALL sessions, exits bot) |
 
 > **Note:** Commands use `!` prefix instead of `/` to avoid conflicts with Mattermost's slash commands.
 
@@ -176,6 +204,47 @@ If the bot is running with `--skip-permissions` (auto mode), you can enable inte
 
 This allows collaboration by requiring approval for Claude's actions. Note: you can only downgrade (auto → interactive), not upgrade - this ensures security.
 
+## Git Worktrees
+
+When working on a task that requires code changes, Claude can work in an isolated git worktree. This keeps your main branch clean while Claude works on a feature branch in a separate directory.
+
+### Starting a Session with a Worktree
+
+Specify a branch when starting:
+
+```
+@claude-code on branch feature/add-auth implement user authentication
+```
+
+Or use the worktree command:
+
+```
+@claude-code !worktree feature/add-auth implement user authentication
+```
+
+### Worktree Commands
+
+| Command | Description |
+|:--------|:------------|
+| `!worktree <branch>` | Create worktree and switch to it |
+| `!worktree list` | List all worktrees for this repo |
+| `!worktree switch <branch>` | Switch to an existing worktree |
+| `!worktree remove <branch>` | Remove a worktree |
+| `!worktree off` | Disable worktree prompts for this session |
+
+### How It Works
+
+1. Creates a new worktree at `../<repo>-worktrees/<branch>/`
+2. Creates or checks out the specified branch
+3. Claude works in the worktree directory
+4. Your main working directory stays untouched
+
+### Environment Variable
+
+| Variable | Description |
+|----------|-------------|
+| `WORKTREE_MODE` | `prompt` (ask on new sessions), `require` (always require branch), `off` (disable) |
+
 ## Interactive Features
 
 ### Permission Approval
@@ -237,10 +306,13 @@ Stop a running session:
 
 ## Access Control
 
-Set `ALLOWED_USERS` to restrict who can use the bot:
+Set `allowedUsers` in your platform config to restrict who can use the bot:
 
-```env
-ALLOWED_USERS=alice,bob,carol
+```yaml
+platforms:
+  - id: mattermost-main
+    # ...
+    allowedUsers: [alice, bob, carol]
 ```
 
 - Only listed users can start sessions
@@ -248,24 +320,57 @@ ALLOWED_USERS=alice,bob,carol
 - Session owners can `!invite` others temporarily
 - Empty = anyone can use (be careful!)
 
-## Environment Variables
+## Configuration
+
+Configuration is stored in YAML format at `~/.config/claude-threads/config.yaml`.
+
+### Example Config
+
+```yaml
+version: 1
+workingDir: /home/user/repos/myproject
+chrome: false
+worktreeMode: prompt
+
+platforms:
+  - id: mattermost-main
+    type: mattermost
+    displayName: Main Team
+    url: https://chat.example.com
+    token: your-bot-token
+    channelId: abc123
+    botName: claude-code
+    allowedUsers: [alice, bob]
+    skipPermissions: false
+```
+
+### Global Settings
+
+| Setting | Description |
+|---------|-------------|
+| `workingDir` | Default working directory for Claude |
+| `chrome` | Enable Chrome integration (`true`/`false`) |
+| `worktreeMode` | Git worktree mode: `off`, `prompt`, or `require` |
+
+### Platform Settings (Mattermost)
+
+| Setting | Description |
+|---------|-------------|
+| `url` | Mattermost server URL |
+| `token` | Bot access token |
+| `channelId` | Channel to listen in |
+| `botName` | Mention name (default: `claude-code`) |
+| `allowedUsers` | List of usernames who can use the bot |
+| `skipPermissions` | Auto-approve actions (`true`/`false`) |
+
+### 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`
+| `DEBUG` | Set to `1` for verbose logging |
 
 ## Code Display
 

package/dist/claude/cli.d.ts

@@ -16,6 +16,13 @@ export interface ImageContentBlock {
     };
 }
 export type ContentBlock = TextContentBlock | ImageContentBlock;
+export interface PlatformMcpConfig {
+    type: string;
+    url: string;
+    token: string;
+    channelId: string;
+    allowedUsers: string[];
+}
 export interface ClaudeCliOptions {
     workingDir: string;
     threadId?: string;
@@ -23,6 +30,7 @@ export interface ClaudeCliOptions {
     sessionId?: string;
     resume?: boolean;
     chrome?: boolean;
+    platformConfig?: PlatformMcpConfig;
 }
 export declare class ClaudeCli extends EventEmitter {
     private process;

package/dist/claude/cli.js

@@ -36,20 +36,28 @@ export class ClaudeCli extends EventEmitter {
         else {
             // Configure the permission MCP server
             const mcpServerPath = this.getMcpServerPath();
+            // Platform config is required for MCP permission server
+            const platformConfig = this.options.platformConfig;
+            if (!platformConfig) {
+                throw new Error('platformConfig is required when skipPermissions is false');
+            }
+            // Platform-agnostic environment variables for MCP permission server
+            const mcpEnv = {
+                PLATFORM_TYPE: platformConfig.type,
+                PLATFORM_URL: platformConfig.url,
+                PLATFORM_TOKEN: platformConfig.token,
+                PLATFORM_CHANNEL_ID: platformConfig.channelId,
+                PLATFORM_THREAD_ID: this.options.threadId || '',
+                ALLOWED_USERS: platformConfig.allowedUsers.join(','),
+                DEBUG: this.debug ? '1' : '',
+            };
             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' : '',
-                        },
+                        env: mcpEnv,
                     },
                 },
             };

package/dist/config/migration.d.ts

@@ -0,0 +1,45 @@
+export declare const CONFIG_PATH: string;
+export type WorktreeMode = 'off' | 'prompt' | 'require';
+export interface NewConfig {
+    version: number;
+    workingDir: string;
+    chrome: boolean;
+    worktreeMode: WorktreeMode;
+    platforms: PlatformInstanceConfig[];
+}
+export interface PlatformInstanceConfig {
+    id: string;
+    type: 'mattermost' | 'slack';
+    displayName: string;
+    [key: string]: unknown;
+}
+export interface MattermostPlatformConfig extends PlatformInstanceConfig {
+    type: 'mattermost';
+    url: string;
+    token: string;
+    channelId: string;
+    botName: string;
+    allowedUsers: string[];
+    skipPermissions: boolean;
+}
+export interface SlackPlatformConfig extends PlatformInstanceConfig {
+    type: 'slack';
+    botToken: string;
+    appToken: string;
+    channelId: string;
+    botName: string;
+    allowedUsers: string[];
+    skipPermissions: boolean;
+}
+/**
+ * Load config from YAML file
+ */
+export declare function loadConfigWithMigration(): NewConfig | null;
+/**
+ * Save config to YAML file
+ */
+export declare function saveConfig(config: NewConfig): void;
+/**
+ * Check if config exists
+ */
+export declare function configExists(): boolean;

package/dist/config/migration.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import YAML from 'yaml';
+import { resolve, dirname } from 'path';
+import { homedir } from 'os';
+// YAML config path
+export const CONFIG_PATH = resolve(homedir(), '.config', 'claude-threads', 'config.yaml');
+// =============================================================================
+// Config Loading
+// =============================================================================
+/**
+ * Load config from YAML file
+ */
+export function loadConfigWithMigration() {
+    if (existsSync(CONFIG_PATH)) {
+        const content = readFileSync(CONFIG_PATH, 'utf-8');
+        return YAML.parse(content);
+    }
+    return null; // No config found
+}
+/**
+ * Save config to YAML file
+ */
+export function saveConfig(config) {
+    const configDir = dirname(CONFIG_PATH);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    writeFileSync(CONFIG_PATH, YAML.stringify(config), 'utf-8');
+}
+/**
+ * Check if config exists
+ */
+export function configExists() {
+    return existsSync(CONFIG_PATH);
+}

package/dist/config.d.ts

@@ -1,7 +1,14 @@
-/** Check if any .env config file exists */
-export declare function configExists(): boolean;
-export type WorktreeMode = 'off' | 'prompt' | 'require';
-/** CLI arguments that can override config */
+/**
+ * Configuration type exports
+ *
+ * Re-exports types from config/migration.ts for convenience.
+ * The actual config loading and migration logic is in config/migration.ts.
+ */
+import type { WorktreeMode as WorktreeModeType } from './config/migration.js';
+export type { NewConfig, PlatformInstanceConfig, MattermostPlatformConfig, WorktreeMode, } from './config/migration.js';
+/**
+ * CLI arguments that can override config
+ */
 export interface CliArgs {
     url?: string;
     token?: string;
@@ -10,18 +17,5 @@ export interface CliArgs {
     allowedUsers?: string;
     skipPermissions?: boolean;
     chrome?: boolean;
-    worktreeMode?: WorktreeMode;
+    worktreeMode?: WorktreeModeType;
 }
-export interface Config {
-    mattermost: {
-        url: string;
-        token: string;
-        channelId: string;
-        botName: string;
-    };
-    allowedUsers: string[];
-    skipPermissions: boolean;
-    chrome: boolean;
-    worktreeMode: WorktreeMode;
-}
-export declare function loadConfig(cliArgs?: CliArgs): Config;

package/dist/config.js

@@ -1,94 +1,7 @@
-import { config } from 'dotenv';
-import { resolve } from 'path';
-import { existsSync } from 'fs';
-import { homedir } from 'os';
-let envLoaded = false;
-// Paths to search for .env files (in order of priority)
-const ENV_PATHS = [
-    resolve(process.cwd(), '.env'), // Current directory
-    resolve(homedir(), '.config', 'claude-threads', '.env'), // ~/.config/claude-threads/.env
-    resolve(homedir(), '.claude-threads.env'), // ~/.claude-threads.env
-];
-function loadEnv() {
-    if (envLoaded)
-        return;
-    envLoaded = true;
-    for (const envPath of ENV_PATHS) {
-        if (existsSync(envPath)) {
-            if (process.env.DEBUG === '1' || process.argv.includes('--debug')) {
-                console.log(`  [config] Loading from: ${envPath}`);
-            }
-            config({ path: envPath });
-            break;
-        }
-    }
-}
-/** Check if any .env config file exists */
-export function configExists() {
-    return ENV_PATHS.some(p => existsSync(p));
-}
-function getRequired(cliValue, envName, name) {
-    const value = cliValue || process.env[envName];
-    if (!value) {
-        throw new Error(`Missing required config: ${name}. Set ${envName} in .env or use --${name.toLowerCase().replace(/ /g, '-')} flag.`);
-    }
-    return value;
-}
-export function loadConfig(cliArgs) {
-    loadEnv();
-    // CLI args take priority over env vars
-    const url = getRequired(cliArgs?.url, 'MATTERMOST_URL', 'url');
-    const token = getRequired(cliArgs?.token, 'MATTERMOST_TOKEN', 'token');
-    const channelId = getRequired(cliArgs?.channel, 'MATTERMOST_CHANNEL_ID', 'channel');
-    const botName = cliArgs?.botName || process.env.MATTERMOST_BOT_NAME || 'claude-code';
-    const allowedUsersStr = cliArgs?.allowedUsers || process.env.ALLOWED_USERS || '';
-    const allowedUsers = allowedUsersStr
-        .split(',')
-        .map(u => u.trim())
-        .filter(u => u.length > 0);
-    // CLI --skip-permissions or --no-skip-permissions takes priority
-    // Then env SKIP_PERMISSIONS, then legacy flag
-    let skipPermissions;
-    if (cliArgs?.skipPermissions !== undefined) {
-        // CLI explicitly set (--skip-permissions or --no-skip-permissions)
-        skipPermissions = cliArgs.skipPermissions;
-    }
-    else {
-        skipPermissions = process.env.SKIP_PERMISSIONS === 'true' ||
-            process.argv.includes('--dangerously-skip-permissions');
-    }
-    // Chrome integration: CLI flag or env var
-    let chrome;
-    if (cliArgs?.chrome !== undefined) {
-        chrome = cliArgs.chrome;
-    }
-    else {
-        chrome = process.env.CLAUDE_CHROME === 'true';
-    }
-    // Worktree mode: CLI flag or env var, default to 'prompt'
-    let worktreeMode;
-    if (cliArgs?.worktreeMode !== undefined) {
-        worktreeMode = cliArgs.worktreeMode;
-    }
-    else {
-        const envValue = process.env.WORKTREE_MODE?.toLowerCase();
-        if (envValue === 'off' || envValue === 'prompt' || envValue === 'require') {
-            worktreeMode = envValue;
-        }
-        else {
-            worktreeMode = 'prompt'; // Default
-        }
-    }
-    return {
-        mattermost: {
-            url: url.replace(/\/$/, ''), // Remove trailing slash
-            token,
-            channelId,
-            botName,
-        },
-        allowedUsers,
-        skipPermissions,
-        chrome,
-        worktreeMode,
-    };
-}
+/**
+ * Configuration type exports
+ *
+ * Re-exports types from config/migration.ts for convenience.
+ * The actual config loading and migration logic is in config/migration.ts.
+ */
+export {};

package/dist/git/worktree.d.ts

@@ -21,10 +21,6 @@ export declare function hasUncommittedChanges(dir: string): Promise<boolean>;
  * List all worktrees for a repository
  */
 export declare function listWorktrees(repoRoot: string): Promise<WorktreeInfo[]>;
-/**
- * Check if a branch exists (local or remote)
- */
-export declare function branchExists(repoRoot: string, branch: string): Promise<boolean>;
 /**
  * Generate the worktree directory path
  * Creates path like: /path/to/repo-worktrees/branch-name-abc123

package/dist/git/worktree.js

@@ -119,7 +119,7 @@ export async function listWorktrees(repoRoot) {
 /**
  * Check if a branch exists (local or remote)
  */
-export async function branchExists(repoRoot, branch) {
+async function branchExists(repoRoot, branch) {
     try {
         // Check local branches
         await execGit(['rev-parse', '--verify', `refs/heads/${branch}`], repoRoot);