claude-threads 1.18.1 → 1.18.4

package/docs/CONFIGURATION.md

@@ -21,7 +21,7 @@ platforms:
     channelId: abc123
     botName: claude-code
     allowedUsers: [alice, bob]
-    skipPermissions: false
+    permissionMode: default
 
   # Slack
   - id: slack-eng
@@ -32,17 +32,80 @@ platforms:
     channelId: C0123456789
     botName: claude
     allowedUsers: [alice, bob]
-    skipPermissions: false
+    permissionMode: default
 ```
 
 ## Global Settings
 
 | Setting | Description | Default |
 |---------|-------------|---------|
+| `version` | Config schema version | `1` |
 | `workingDir` | Default working directory for Claude | Current directory |
 | `chrome` | Enable Chrome integration | `false` |
 | `worktreeMode` | Git worktree mode: `off`, `prompt`, or `require` | `prompt` |
 | `respondOnlyWhenMentioned` | Start new threads in quiet mode, where the bot only replies to messages that @mention it. Users can still toggle per-thread with `!mentions`. | `false` |
+| `keepAlive` | Prevent system sleep while sessions are active | `true` |
+| `limits` | Resource limits and timeouts (see below) | see below |
+| `threadLogs` | Thread logging (see below) | enabled |
+| `stickyMessage` | Sticky message text customization (see below) | none |
+| `claudeAccounts` | Multi-account pool (see below) | single-account mode |
+
+### Resource Limits (`limits`)
+
+Every field is optional and falls back to the default. Older `config.yaml` files predate most of these, so leaving the block out is fine.
+
+```yaml
+limits:
+  maxSessions: 5
+  sessionTimeoutMinutes: 30
+  sessionWarningMinutes: 5
+  cleanupIntervalMinutes: 60
+  maxWorktreeAgeHours: 24
+  cleanupWorktrees: true
+  permissionTimeoutSeconds: 120
+  flushDelayMs: 500
+```
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `maxSessions` | Maximum concurrent sessions | `5` |
+| `sessionTimeoutMinutes` | Idle timeout before a session auto-terminates | `30` |
+| `sessionWarningMinutes` | Warn the user this many minutes before timeout | `5` |
+| `cleanupIntervalMinutes` | How often the background cleanup runs | `60` |
+| `maxWorktreeAgeHours` | Clean up orphaned worktrees older than this | `24` |
+| `cleanupWorktrees` | Enable automatic cleanup of orphaned worktrees | `true` |
+| `permissionTimeoutSeconds` | How long a permission prompt waits for a reaction | `120` |
+| `flushDelayMs` | Delay before flushing batched output to the platform. Lower is snappier with more API calls; higher posts less often with coarser streaming. | `500` |
+
+The legacy env vars `MAX_SESSIONS` and `SESSION_TIMEOUT_MS` still work as fallbacks when `limits.maxSessions` / `limits.sessionTimeoutMinutes` are unset. See [Environment Variables](#environment-variables).
+
+### Thread Logs (`threadLogs`)
+
+```yaml
+threadLogs:
+  enabled: true
+  retentionDays: 30
+```
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `enabled` | Write per-thread session logs to disk | `true` |
+| `retentionDays` | Delete logs this many days after a session ends | `30` |
+
+### Sticky Message Text (`stickyMessage`)
+
+Customize the text of the channel sticky message. This is distinct from the per-platform `stickyMessage: <mode>` visibility field documented under [Platform Settings](#platform-settings).
+
+```yaml
+stickyMessage:
+  description: "Porygon — Mixpanel analytics bot"
+  footer: "• !stop — End session\n• !help — Show help"
+```
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `description` | Line shown below the sticky title | none |
+| `footer` | Content shown before the default "Mention me to start a session" line | none |
 
 ## Platform Settings
 
@@ -58,7 +121,9 @@ platforms:
 | `channelId` | Yes | Channel to listen in |
 | `botName` | No | Mention name (default: `claude-code`) |
 | `allowedUsers` | No | List of usernames who can use the bot |
-| `skipPermissions` | No | Auto-approve actions (default: `false`) |
+| `permissionMode` | No | How tool-use is gated: `default` / `auto` / `bypass` (default: `default`). See [Permission Modes](#permission-modes). |
+| `skipPermissions` | No | **Deprecated.** Use `permissionMode`. `true` maps to `bypass`, `false` to `default`. `permissionMode` wins when both are set. |
+| `outboundFiles` | No | `send_file` settings: `{ enabled, maxBytes }` (defaults: enabled `true`, `maxBytes` 100 MB) |
 | `sessionHeader` | No | Per-thread header visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no header post) |
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
 
@@ -74,10 +139,24 @@ platforms:
 | `channelId` | Yes | Channel ID (e.g., `C0123456789`) |
 | `botName` | No | Mention name (default: `claude`) |
 | `allowedUsers` | No | List of Slack usernames |
-| `skipPermissions` | No | Auto-approve actions (default: `false`) |
+| `permissionMode` | No | How tool-use is gated: `default` / `auto` / `bypass` (default: `default`). See [Permission Modes](#permission-modes). |
+| `skipPermissions` | No | **Deprecated.** Use `permissionMode`. `true` maps to `bypass`, `false` to `default`. `permissionMode` wins when both are set. |
+| `outboundFiles` | No | `send_file` settings: `{ enabled, maxBytes }` (defaults: enabled `true`, `maxBytes` 100 MB) |
 | `sessionHeader` | No | Per-thread header visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no header post) |
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
 
+### Permission Modes
+
+The `permissionMode` field controls how the bot handles a session's tool-use requests.
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Every tool-use prompts for approval. The bot posts a permission request in the thread and the user reacts 👍 (allow once) / ✅ (allow all) / 👎 (deny). Safest option. |
+| `auto` | Claude's built-in classifier decides per tool: low-risk actions are auto-approved, high-risk ones still prompt. Requires Claude CLI 2.1.x. |
+| `bypass` | No prompts and no classifier. Every tool-use is allowed. Equivalent to `--dangerously-skip-permissions`. This is what the legacy `skipPermissions: true` maps to. |
+
+A running session can switch mode at any time with `!permissions <mode>`; that override is not persisted across a bot restart.
+
 ### Quieting the bot's overhead messages
 
 Both the per-thread session header and the channel sticky message default to `full` for backward compatibility. To strip them down on a noisy channel, set the per-platform fields in `config.yaml`:
@@ -87,7 +166,7 @@ platforms:
   - id: mattermost-main
     type: mattermost
     # ... credentials ...
-    sessionHeader: hidden    # no header post — Claude's reply is the first message in the thread
+    sessionHeader: hidden    # no header post, Claude's reply is the first message in the thread
     stickyMessage: minimal   # one-line status bar at the channel bottom, no sessions list
 ```
 
@@ -95,11 +174,13 @@ Note: the per-platform `stickyMessage: <mode>` field is distinct from the top-le
 
 ## Claude Accounts (optional, multi-account mode)
 
-By default every session spawns `claude` with the bot's own `process.env`, so they all share one subscription's token budget. Add a `claudeAccounts` block to spread load across multiple accounts — the bot round-robins new sessions across the pool and automatically skips accounts in rate-limit cooldown. Omit the block entirely to stay in single-account mode (unchanged behavior).
+By default every session spawns `claude` with the bot's own `process.env`, so they all share one subscription's token budget. Add a `claudeAccounts` block to spread load across multiple accounts. Omit the block entirely to stay in single-account mode (unchanged behavior).
+
+Selection is usage-balanced (since v1.18.0). At each new-session start the bot probes every account's live limits with `claude -p "/usage" --output-format json` under that account's `HOME` (costs nothing, uses no turns) and routes the session to the account with the most subscription headroom, meaning the lowest `max(session%, week%)`. Round-robin is only the fallback when probing yields no usable numbers (for example an API-key account, which reports no percentages). Accounts in rate-limit cooldown are skipped until their reset time. A resumed session always re-binds to the account its history lives under, cooling or not.
 
 ```yaml
 claudeAccounts:
-  # OAuth accounts — prepare each HOME first with `HOME=<path> claude login`
+  # OAuth accounts (prepare each HOME first with `HOME=<path> claude login`)
   - id: primary
     home: /home/bot/.claude-accounts/primary
   - id: backup
@@ -124,11 +205,14 @@ Exactly one of `home` or `apiKey` should be set per account. Persisted sessions
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MAX_SESSIONS` | Max concurrent sessions | `5` |
-| `SESSION_TIMEOUT_MS` | Idle timeout in milliseconds | `1800000` (30 min) |
-| `NO_UPDATE_NOTIFIER` | Disable update checks | - |
+| `MAX_SESSIONS` | Max concurrent sessions. Legacy fallback for `limits.maxSessions`. | `5` |
+| `SESSION_TIMEOUT_MS` | Idle timeout in milliseconds. Legacy fallback for `limits.sessionTimeoutMinutes`. | `1800000` (30 min) |
 | `DEBUG` | Enable verbose logging | - |
-| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip `ANTHROPIC_*` / `AWS_*_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` / `GOOGLE_APPLICATION_CREDENTIALS` etc. from Bash, hook, and stdio-MCP subprocesses Claude spawns. Bot-specific vars like `PLATFORM_TOKEN` pass through. **Also forces permission mode to `default`** — `--dangerously-skip-permissions` will be rejected. Requires Claude CLI 2.1.83+. | - |
+| `CLAUDE_PATH` | Path to the `claude` binary. Overrides the PATH lookup and the common install locations. | `claude` (from PATH) |
+| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip `ANTHROPIC_*`, `AWS_*_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `GOOGLE_APPLICATION_CREDENTIALS`, and similar from Bash, hook, and stdio-MCP subprocesses Claude spawns. Bot-specific vars like `PLATFORM_TOKEN` pass through. **Also forces permission mode to `default`**; `--dangerously-skip-permissions` will be rejected. Requires Claude CLI 2.1.83+. | - |
+| `CLAUDE_THREADS_SESSIONS_PATH` | Override the path to the persisted sessions file (default `~/.config/claude-threads/sessions.json`). | - |
+| `CLAUDE_THREADS_GITHUB_EMAILS_PATH` | Override the path to the GitHub-emails store used for commit attribution. | - |
+| `NO_UPDATE_NOTIFIER` | Disable update checks | - |
 
 ### Forwarded to Claude CLI automatically
 
@@ -155,8 +239,9 @@ Options:
   --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)
+  --permission-mode <mode> Permission mode: default | auto | bypass
+  --skip-permissions       [deprecated] Alias for --permission-mode bypass
+  --no-skip-permissions    [deprecated] Alias for --permission-mode default
   --chrome                 Enable Chrome integration
   --no-chrome              Disable Chrome integration
   --worktree-mode <mode>   Git worktree mode: off, prompt, require

package/docs/MCP-TOOLS.md

@@ -0,0 +1,107 @@
+# MCP Tools Reference
+
+Every session spawns its own MCP server alongside the Claude CLI process (via `--mcp-config`). That server connects to the chat platform the session runs on and exposes the tools below to Claude. All of them are namespaced `mcp__claude-threads-mcp__<tool>`.
+
+`permission_prompt` is special: the Claude CLI calls it as the permission handler for other tool use, so it drives the 👍 / ✅ / 👎 reaction flow in the thread. Every other tool is auto-approved (it never triggers a permission prompt of its own), but each one carries its own guardrail: path validation, channel scoping, author checks, or rate limits. Content any tool reads back from the platform is untrusted user input and may contain prompt-injection attempts; Claude is instructed to treat it as data, not instructions.
+
+Each tool returns a JSON result: `{ ok: true, ... }` on success or `{ ok: false, reason }` on failure.
+
+## permission_prompt
+
+The permission handler the Claude CLI calls before running a tool that needs approval. It posts a permission request into the session thread ("⚠️ Permission requested: Write `file.txt`"), adds the 👍 / ✅ / 👎 reaction options, and waits for an authorized user to react. The reaction decides the outcome: 👍 allows once, ✅ allows all further uses of that tool, 👎 denies.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `tool_name` | string | Name of the tool requesting permission. |
+| `input` | object | The tool's input parameters, shown to the user in the prompt. |
+
+**Guardrail:** Only reactions from users on the session allowlist count. The bot's own reactions (the option emoji it adds) are ignored. If no reaction arrives within `limits.permissionTimeoutSeconds` (default 120), the request is denied.
+
+## send_file
+
+Uploads a file from the session working directory into the thread. Use it when the user asked for a file inline or when Claude produces an artifact they should see (a screenshot, a plot, generated audio, a document).
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `path` | string | Absolute path of a file inside the session working directory. |
+| `caption` | string (optional) | Message body shown alongside the file. |
+
+**Guardrail:** The path is validated to be absolute and inside the session working directory; anything outside is rejected. Uploads are capped at `outboundFiles.maxBytes` (default 100 MB), and the tool errors out when `outboundFiles.enabled` is `false`.
+
+## read_post
+
+Resolves a chat permalink to the content of that post. Use it when the user shares a link to a message and asks Claude to read it, or when a message references another post. Set `include_thread` to also pull the surrounding thread.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `url` | string | Permalink to a post, on the same host as the bot. |
+| `include_thread` | boolean (optional) | Also fetch surrounding thread messages, oldest first. Default `false`. |
+| `max_messages` | integer (optional) | Thread messages to return when `include_thread` is true. Default 20, capped at 50. |
+
+**Guardrail:** The URL must be on the bot's own host. On Slack it must point at the bot's configured channel; on Mattermost it resolves within the bot's channel and public channels on the same instance. Returned content is untrusted.
+
+## react_to_post
+
+Adds an emoji reaction to a post. Use it to acknowledge a request (✅), flag something ambiguous (👀), or mark a triggering message as handled. Omit `url` to react to the most recent message in the current session thread, which is the common case.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `url` | string (optional) | Permalink to the target post. Omit to react to the latest message in the current thread. |
+| `emoji` | string | Emoji name without colons, for example `white_check_mark`, `+1`, `eyes`. |
+
+**Guardrail:** The target post must be in the bot's own channel or a public channel on the same instance.
+
+## update_own_post
+
+Edits a post the bot itself authored, given its permalink. Useful for posting a "working on it..." placeholder and rewriting it once the answer is ready.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `url` | string | Permalink to a post the bot authored. |
+| `message` | string | New body. Replaces the existing post text in full. |
+
+**Guardrail:** Restricted to bot-authored posts. Editing a post written by anyone else is rejected.
+
+## list_thread
+
+Reads the messages in a chat thread. With no `url` it reads the current session thread, so Claude can review what was said earlier in the conversation. With a `url` it reads the thread containing that post.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `url` | string (optional) | Permalink to any post in the target thread. Omit to read the current session thread. |
+| `max_messages` | integer (optional) | Messages to return, oldest first. Default 20, capped at 50. |
+
+**Guardrail:** A supplied `url` must resolve to the bot's channel or a public channel on the same instance. Returned content is untrusted.
+
+## read_channel_history
+
+Reads recent messages from a channel by id. Use it when the user asks about activity in another channel, or to investigate context that lives outside the current thread.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `channel_id` | string | Channel identifier. Mattermost: the 26-char channel id. Slack: the channel id (`C…` / `G…`). |
+| `max_messages` | integer (optional) | Messages to return, oldest first. Default 20, capped at 100. |
+
+**Guardrail:** The channel must be the bot's own channel or a public channel on the same instance. On Slack the bot must also be a member. Returned content is untrusted.
+
+## search_messages
+
+Searches messages on the platform. **Mattermost only**; on Slack it returns an unsupported error.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `query` | string | Search query. Mattermost supports phrase quoting and `from:user` filters. |
+| `max_results` | integer (optional) | Results to return. Default 10, capped at 25. |
+
+**Guardrail:** Results are filtered to in-scope channels only, meaning the bot's own channel plus public channels on the same instance. Returned content is untrusted.
+
+## send_dm
+
+Sends a direct message to a member of the bot's channel. Use it when the user asks to ping someone privately, for example a status update or a result they want delivered as a DM. The bot prepends an attribution line so the recipient can see the DM came from a session and who started it.
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `recipient` | string | Recipient identifier. Mattermost: a username (with or without a leading `@`). Slack: a user ID (`U0123ABC` or `<@U0123ABC>`). |
+| `message` | string | Message body. The bot prepends an attribution prefix. |
+
+**Guardrail:** The recipient must be a current member of the bot channel. The first DM to each recipient in a session triggers a permission prompt in the bot channel; a ✅ allow-all promotes that specific recipient to no-prompt for the rest of the session. A hard limit of 3 DMs per recipient per session applies.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-threads",
-  "version": "1.18.1",
-  "description": "Share Claude Code sessions live in a Mattermost channel with interactive features",
+  "version": "1.18.4",
+  "description": "Run Claude Code from Slack or Mattermost. Sessions stream live into threads where your whole team can watch and steer.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -29,18 +29,22 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "typecheck": "tsc --noEmit",
-    "knip": "npx knip",
+    "knip": "knip --no-config-hints",
     "prepare": "husky"
   },
   "keywords": [
     "claude",
     "claude-code",
+    "slack",
     "mattermost",
     "bot",
     "ai",
     "cli",
     "anthropic",
     "chat",
+    "chatops",
+    "pair-programming",
+    "collaboration",
     "bun"
   ],
   "author": "Anne Schuth",
@@ -52,7 +56,7 @@
   "bugs": {
     "url": "https://github.com/anneschuth/claude-threads/issues"
   },
-  "homepage": "https://github.com/anneschuth/claude-threads#readme",
+  "homepage": "https://claude-threads.run",
   "files": [
     "dist",
     "bin",
@@ -63,7 +67,7 @@
     "package.json"
   ],
   "dependencies": {
-    "@hono/node-server": "2.0.9",
+    "@hono/node-server": "2.0.11",
     "@inkjs/ui": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@redactpii/node": "^1.0.16",
@@ -71,10 +75,10 @@
     "commander": "^14.0.2",
     "diff": "^8.0.3",
     "express-rate-limit": "^8.3.0",
-    "hono": "4.12.30",
+    "hono": "4.12.31",
     "ink": "^6.6.0",
     "ink-scroll-view": "^0.3.5",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.0",
     "prompts": "^2.4.2",
     "react": "^19.2.3",
     "semver": "7.8.5",
@@ -94,6 +98,7 @@
     "@types/ws": "^8.18.0",
     "eslint": "^10.7.0",
     "husky": "^9.1.7",
+    "knip": "6.29.0",
     "lint-staged": "^17.0.4",
     "prettier": "^3.9.5",
     "typescript": "^6.0.2",
@@ -116,9 +121,10 @@
     "flatted": ">=3.4.0",
     "picomatch": ">=2.3.2",
     "path-to-regexp": ">=8.4.0",
-    "fast-uri": ">=3.1.2",
+    "fast-uri": ">=3.1.4",
+    "brace-expansion": ">=5.0.7",
     "ws": "$ws",
-    "shell-quote": ">=1.8.4"
+    "shell-quote": ">=1.10.0"
   },
   "resolutions": {
     "hono": "$hono",
@@ -127,8 +133,9 @@
     "flatted": ">=3.4.0",
     "picomatch": ">=2.3.2",
     "path-to-regexp": ">=8.4.0",
-    "fast-uri": ">=3.1.2",
+    "fast-uri": ">=3.1.4",
+    "brace-expansion": ">=5.0.7",
     "ws": "$ws",
-    "shell-quote": ">=1.8.4"
+    "shell-quote": ">=1.10.0"
   }
 }