claude-threads 1.18.1 → 1.18.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.18.2] - 2026-07-17
+
+### Changed
+- **New visual identity: the thread-spine mark.** The ✴-star ASCII logo (a leftover of the Claude Code Christmas logo) is replaced everywhere by a mark of our own: heavy box-drawing CT letters with a light thread gutter showing a root node, a reply branch, and a closing arc. Applied consistently to the terminal header, the favicon, a rebuilt pure-vector `logo.svg` with no font dependency, the README, and the website. (#431)
+- **README overhaul.** Screenshots for both platforms directly under the pitch, a How it works section, a table of all nine MCP tools with their guardrails (seven were previously undocumented), and a command table synced with the registry. Corrected copy along the way: multi-account selection is usage-balanced since 1.18.0 (the README still said round-robin), the resume reaction is 🔄 (the documented ↩️ was never accepted), and the `send_dm` guardrail is approved from the session thread, not by the recipient. Cross-file links are now absolute so they no longer break on the npm package page, and the configuration link points at `docs/CONFIGURATION.md` instead of the internal `CLAUDE.md`. (#431)
+- **Docs sync.** `docs/CONFIGURATION.md` audited against the real config schema: the `limits` block, `threadLogs`, sticky text customization, permission modes, `outboundFiles`, usage-balanced accounts, and the env var list. New `docs/MCP-TOOLS.md` documents every MCP tool with inputs and guardrails. `SETUP_GUIDE.md` drops stale version pins and deprecated permission vocabulary; `CONTRIBUTING.md` gains dev commands and a pointer to the platform implementation guide. (#431)
+- **Website redesign: the page is a thread.** claude-threads.run rebuilt on the same terminal identity with the thread as its structure: a rail runs down the content and every section attaches to it as a reply, the last one closing the arc. Content synced with 1.18 (MCP tools table, full command list, a Mattermost showcase section), OpenGraph/Twitter cards with a generated social image, and the Node prerequisite corrected from 18+ to 20+. (#432)
+- **npm metadata.** The package description finally mentions Slack, keywords gain `slack`, `chatops`, `pair-programming`, and `collaboration`, and the homepage points at claude-threads.run. Takes effect with this release. (#431)
+
 ## [1.18.1] - 2026-07-17
 
 ### Changed

package/README.md

@@ -1,10 +1,10 @@
 # Claude Threads
 
-```
- ✴ ▄█▀ ███ ✴   claude-threads
-✴  █▀   █   ✴  Mattermost & Slack × Claude Code
- ✴ ▀█▄  █  ✴
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anneschuth/claude-threads/main/website/assets/logo.svg" alt="claude-threads logo: a chat-thread spine next to the letters CT" width="200">
+</p>
+
+<p align="center"><sub>Claude Code × Slack &amp; Mattermost</sub></p>
 
 <p align="center">
   <a href="https://claude-threads.run"><strong>claude-threads.run</strong></a>
@@ -18,28 +18,64 @@
 [![Node](https://img.shields.io/node/v/claude-threads.svg)](https://nodejs.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/anneschuth/claude-threads/pulls)
 
-**Bring Claude Code to your team.** Run Claude Code on your machine, share it live in Mattermost or Slack. Colleagues can watch, collaborate, and run their own sessions—all from chat.
+**Run Claude Code from your team's chat.** The bot lives on your machine, next to your checkout and your local tools. Sessions stream live into Slack or Mattermost threads where teammates watch and steer what Claude does. No cloud sandbox and no enterprise plan required: it works with the Claude subscription or API key you already have.
 
 > _Think of it as screen-sharing for AI pair programming, but everyone can type._
 
+<table>
+  <tr>
+    <td width="50%" valign="top"><img src="https://raw.githubusercontent.com/anneschuth/claude-threads/main/website/assets/screenshots/slack-thread.png" alt="A Claude Code session streaming into a Slack thread, with session header badges and live tool output"></td>
+    <td width="50%" valign="top"><img src="https://raw.githubusercontent.com/anneschuth/claude-threads/main/website/assets/screenshots/mattermost-thread.png" alt="The same bot in a Mattermost thread, showing the session header table and Claude's reply"></td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Slack</sub></td>
+    <td align="center"><sub>Mattermost</sub></td>
+  </tr>
+</table>
+
+## How it works
+
+1. Mention the bot in a channel: `@claude fix the flaky test in ci.yml`
+2. It spawns a real Claude Code session in a working directory on your machine.
+3. Everything streams into the thread: output, diffs, task lists, permission prompts.
+4. Steer by replying in the thread or reacting with emoji. Anyone you invite can do the same.
+
 ## Features
 
-- **Real-time streaming** - Claude's responses stream live to chat
-- **Multi-platform** - Connect to multiple Mattermost and Slack workspaces simultaneously
-- **Concurrent sessions** - Each thread gets its own Claude session, persisted across bot restarts
-- **Collaboration** - `!invite` teammates to participate; they get added as `Co-Authored-By:` trailers on Claude's commits
-- **Permission modes** - Three-way control over Claude's tool-use: `default` (every action prompts for 👍/✅/👎 approval via emoji), `auto` (Claude's classifier auto-approves low-risk; high-risk still prompts — recommended), or `bypass` (no prompts, all tools allowed). Set via config, `--permission-mode` CLI flag, or in-session with `!permissions default|auto|bypass`.
-- **Claude posts back to chat** - Claude can call `send_file` to drop screenshots, generated PDFs, plots, or audio directly into the thread, and `read_post` to follow a Mattermost or Slack permalink the user shares
-- **Git worktrees** - Isolate Claude's changes in a branch with `!worktree feature/foo`; supports `list`, `switch`, `remove`, `cleanup`, `off`
-- **File attachments** - Drop images, PDFs, archives, or any file into the chat; Claude reads them from disk via its own `Read`/Bash tools (100 MB cap)
-- **Chrome automation** - Optional integration with Claude in Chrome for web tasks
-- **Multi-account Claude (opt-in)** - Round-robin sessions across multiple Claude subscriptions or API keys with automatic rate-limit cooldown — see [Configuration](docs/CONFIGURATION.md#claude-accounts-optional-multi-account-mode)
-- **Auto-update** - Bot checks npm for new versions and offers to restart; `!update now` / `!update defer` controls the timing
+- **Live streaming** - Responses, tool calls, diffs, and a sticky task list render in the thread as the session runs
+- **Slack and Mattermost** - Connect multiple workspaces at once. Mattermost support means this also works where chat is self-hosted and cloud assistants cannot go
+- **A session per thread** - Concurrent sessions, each with its own working directory, resumed automatically after a bot restart
+- **Your machine, your setup** - Sessions use your local checkout plus whatever MCP servers and plugins you already configured
+- **Your existing subscription** - Any Claude Pro/Max account or API key works. An optional multi-account pool routes each new session to the account with the most subscription headroom and cools down rate-limited ones ([docs](https://github.com/anneschuth/claude-threads/blob/main/docs/CONFIGURATION.md#claude-accounts-optional-multi-account-mode))
+- **Permission control by emoji** - `default` prompts the thread for every tool use (👍/✅/👎), `auto` lets Claude's classifier approve low-risk actions, `bypass` skips prompts entirely. Switch per session with `!permissions`
+- **Collaboration** - `!invite` teammates into a session; commits Claude makes get `Co-Authored-By:` trailers for everyone involved
+- **A real chat citizen** - Nine MCP tools let Claude post files, follow permalinks, react, and DM, each behind its own guardrail (see [What Claude can do in your chat](#what-claude-can-do-in-your-chat))
+- **Git worktrees** - `!worktree feature/foo` isolates Claude's changes on a branch
+- **Files both ways** - Drop any file into the chat for Claude to read, with full multimodal for images and PDFs; Claude posts screenshots, plots, or PDFs back with `send_file` (100 MB cap)
+- **Quiet mode and verbosity dials** - `!mentions on` makes a session respond only when mentioned; session headers and the channel sticky each have `full`/`minimal`/`hidden` modes
+- **Runs on macOS, Linux, and Windows** - Windows via Git Bash or WSL
+- **Auto-update** - The bot watches npm for new versions; `!update now` applies one from chat
+
+## What Claude can do in your chat
+
+Each session runs its own MCP server, giving Claude tools that act on the chat platform. Every tool carries its own guardrail; nothing reaches beyond the channels the bot can already see.
+
+| Tool                   | What Claude does with it                              | Guardrail                                                     |
+| :--------------------- | :---------------------------------------------------- | :------------------------------------------------------------ |
+| `send_file`            | Post a file from the working directory into the thread | Path validated against the session working directory          |
+| `read_post`            | Resolve a Slack or Mattermost permalink to its content | Bot's channel plus public channels only                       |
+| `list_thread`          | Read the current thread, or a permalinked one          | Same channel scoping                                          |
+| `read_channel_history` | Read recent messages from a channel                    | Bot's channel plus public channels, capped at 100 messages    |
+| `search_messages`      | Search messages                                        | Mattermost only, capped at 25 results                         |
+| `react_to_post`        | Add an emoji reaction                                  | Defaults to the message that triggered it                     |
+| `update_own_post`      | Edit one of its earlier posts                          | Bot-authored posts only                                       |
+| `send_dm`              | Send a direct message to a channel member              | 3 per recipient per session; the thread approves each one     |
+| `permission_prompt`    | Ask the thread to approve a tool use                   | This one _is_ the approval flow (👍/✅/👎)                    |
+
+The full reference, including inputs and scoping rules, is in [docs/MCP-TOOLS.md](https://github.com/anneschuth/claude-threads/blob/main/docs/MCP-TOOLS.md).
 
 ## Quick Start
 
-### Install & Run
-
 ```bash
 # Install (pick one)
 bun install -g claude-threads   # with Bun (recommended)
@@ -50,23 +86,14 @@ cd /your/project
 claude-threads
 ```
 
-The **interactive setup wizard** will guide you through everything:
+The interactive wizard configures your Slack or Mattermost bot, tests the credentials, and gets you running in minutes. For creating the bot account itself, follow the [Setup Guide](https://github.com/anneschuth/claude-threads/blob/main/SETUP_GUIDE.md).
 
-- Configure Claude Code CLI (if needed)
-- Set up your Mattermost or Slack bot
-- Test credentials and permissions
-- Get you up and running in minutes
-
-**Need help with platform setup?** See the [Setup Guide](SETUP_GUIDE.md) for Mattermost or Slack bot creation.
-
-### Prerequisites
+**Prerequisites**
 
 - **Bun 1.2.21+** or **Node 20+** - [Install Bun](https://bun.sh/) or [Install Node](https://nodejs.org/)
-- **Claude Code CLI working** - test with `claude --version` (needs API key or subscription)
-
-### Use
+- **Claude Code CLI** - test with `claude --version` (needs a subscription or API key)
 
-Mention the bot in your chat:
+Then mention the bot in your channel:
 
 ```
 @claude help me fix the bug in src/auth.ts
@@ -93,33 +120,28 @@ Type `!help` in any session thread:
 | `!github-email <email>`                     | Register your GitHub noreply email so `!invite` can attribute commits to you             |
 | `!update`                                   | Show auto-update status (`!update now` / `!update defer`)                                |
 | `!bug <desc>`                               | Report a bug with context (creates a GitHub issue)                                       |
-| `!approve`                                  | Approve pending plan (alternative to 👍 reaction)                                        |
-| `!escape`                                   | Interrupt current task (session stays active)                                            |
-| `!stop`                                     | Stop this session                                                                        |
+| `!approve`                                  | Approve pending plan (alternative to 👍; also `!yes`)                                    |
+| `!escape`                                   | Interrupt current task, session stays active (also `!interrupt`)                         |
+| `!stop`                                     | Stop this session (also `!cancel`)                                                       |
 | `!kill`                                     | Emergency shutdown (kills ALL sessions and exits the bot)                                |
 
+Unknown `!commands` are checked against Claude Code's own slash commands and passed through when they match.
+
 ## Interactive Controls
 
-**Permission approval** - When Claude wants to execute a tool:
+**Permission approval** - When Claude wants to run a tool:
 
 - 👍 Allow this action
 - ✅ Allow all future actions
 - 👎 Deny
 
-**Plan approval** - When Claude creates a plan:
-
-- 👍 Approve and start
-- 👎 Request changes
+**Plan approval** - When Claude presents a plan: 👍 approve, 👎 request changes
 
 **Questions** - React with 1️⃣ 2️⃣ 3️⃣ 4️⃣ to answer multiple choice
 
-**Session control** - ⏸️ to interrupt, ❌ or 🛑 to stop, ↩️ to resume a timed-out session
+**Session control** - ⏸️ interrupt, ❌ or 🛑 stop, 🔄 resume a timed-out session
 
-## File Attachments
-
-Drop any file into the chat (image, PDF, archive, source, log, you name it). The bot saves it to a per-thread directory and prepends the path to your message; Claude reads it with its own `Read` tool (full multimodal for images and PDFs) or processes it via Bash. Single 100 MB cap per file. Need to extract a zip? Claude runs `unzip` itself.
-
-Going the other way, Claude can post files back into the thread (screenshots, generated PDFs, plots, MP3s) by calling the `send_file` MCP tool. Path is validated against the session working directory; auto-approved so the user doesn't have to 👍 every screenshot.
+**Housekeeping** - 🔽 collapses long task lists and subagent output; 🐛 on an error post opens a bug report
 
 ## Collaboration
 
@@ -128,13 +150,9 @@ Going the other way, Claude can post files back into the thread (screenshots, ge
 !kick @colleague      # Remove access
 ```
 
-Unauthorized users can request message approval from the session owner with a 👍 reaction.
-
-Invited collaborators are added as `Co-Authored-By:` trailers on any commits Claude makes during the session. Each collaborator runs `!github-email <their-noreply-address>` once (find yours at <https://github.com/settings/emails>) and the bot remembers it across sessions.
-
-## Sharing Links With Claude
+Messages from users outside the session can be approved one at a time by the session owner with a 👍 reaction.
 
-Paste a Mattermost or Slack permalink in the thread and Claude can resolve it to the post body (and optional thread context) via the `read_post` MCP tool, instead of asking you to copy-paste. Auto-approved; scoped to channels the bot can already see.
+Invited collaborators end up as `Co-Authored-By:` trailers on commits Claude makes during the session. Each collaborator runs `!github-email <their-noreply-address>` once (find yours at <https://github.com/settings/emails>) and the bot remembers it across sessions.
 
 ## Git Worktrees
 
@@ -148,14 +166,17 @@ Or mid-session: `!worktree feature/add-auth`
 
 ## Access Control
 
-Restrict who can use the bot during setup (or reconfigure later with `claude-threads --setup`).
+Restrict who can use the bot during setup, or reconfigure later with `claude-threads --setup`. An empty allowlist lets anyone in the channel start sessions, so leave it empty only in channels you trust.
 
-Leave the allowed users list empty to let anyone in the channel use the bot (be careful!)
+Who may do what (start sessions, react to permission prompts, approve guest messages) is written down in the [authorization model](https://github.com/anneschuth/claude-threads/blob/main/SECURITY.md).
 
 ## Documentation
 
-- **[Setup Guide](SETUP_GUIDE.md)** - Step-by-step setup for Mattermost and Slack
-- **[Configuration Reference](CLAUDE.md)** - Technical details and architecture
+- **[Setup Guide](https://github.com/anneschuth/claude-threads/blob/main/SETUP_GUIDE.md)** - Creating the bot account on Mattermost or Slack, step by step
+- **[Configuration Reference](https://github.com/anneschuth/claude-threads/blob/main/docs/CONFIGURATION.md)** - Every `config.yaml` option, environment variables, CLI flags
+- **[MCP Tools Reference](https://github.com/anneschuth/claude-threads/blob/main/docs/MCP-TOOLS.md)** - The nine tools Claude gets in chat, with their guardrails
+- **[Security Model](https://github.com/anneschuth/claude-threads/blob/main/SECURITY.md)** - Authorization matrix and vulnerability reporting
+- **[Changelog](https://github.com/anneschuth/claude-threads/blob/main/CHANGELOG.md)** - Detailed release history
 
 ## Updates
 
@@ -163,7 +184,7 @@ Leave the allowed users list empty to let anyone in the channel use the bot (be
 npm install -g claude-threads
 ```
 
-The bot checks for updates automatically and notifies you when new versions are available.
+The bot checks npm for new versions on its own and offers the update in chat.
 
 ## License
 

package/dist/index.js

@@ -76335,22 +76335,12 @@ function Header({ version, workingDir, claudeVersion }) {
       /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
         children: [
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: " ✴"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: " "
+            color: "gray",
+            children: "●─ "
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             color: "blue",
-            children: "▄█▀ ███"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: " "
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: "✴"
+            children: "┏━ ━┳━"
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             children: "   "
@@ -76371,25 +76361,15 @@ function Header({ version, workingDir, claudeVersion }) {
       /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
         children: [
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: "✴"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: "  "
+            color: "gray",
+            children: "├─ "
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             color: "blue",
-            children: "█▀   █"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: "   "
+            children: "┃   ┃"
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: "✴"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: "  "
+            children: "    "
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             dimColor: true,
@@ -76400,28 +76380,15 @@ function Header({ version, workingDir, claudeVersion }) {
       /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
         children: [
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: " "
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: "✴"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: " "
+            color: "gray",
+            children: "╰─ "
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             color: "blue",
-            children: "▀█▄  █"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: "  "
+            children: "┗━  ╹"
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            color: "yellow",
-            children: "✴"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-            children: "   "
+            children: "    "
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             color: "cyan",

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.2",
+  "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": {
@@ -35,12 +35,16 @@
   "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",