claude-threads Setup Guide

💡 Quick Start: Run claude-threads and the interactive wizard will guide you through setup. Use this guide when you need help creating bot accounts on Mattermost or Slack.

Mattermost Setup - Create bot account and get credentials
Slack Setup - Create Slack app with Socket Mode
Running the Onboarding - Interactive wizard walkthrough
Troubleshooting - Common issues and solutions

Mattermost Setup

Step 1: Create a Bot Account

Navigate to Integrations:
- Go to your Mattermost workspace
- Click Main Menu (≡) → Integrations → Bot Accounts
- Click Add Bot Account
Configure the Bot:
- Username: Choose a username (e.g., claude-code, claude-bot)
- Display Name: Choose a display name (e.g., "Claude Code Assistant")
- Description: Optional description
- Role: Select Member (bot doesn't need admin privileges)
- Post:All: ✅ Enable (bot needs to post messages)
- Post:Channels: ✅ Enable (bot needs to post in channels)
- Click Create Bot Account
Save the Token:
- After creation, Mattermost will show you a Bot Token (starts with a long alphanumeric string)
- ⚠️ Copy this token immediately - you won't see it again!
- Keep it secure - treat it like a password

Step 2: Get Channel ID

Open the channel where you want claude-threads to operate
Click the channel name at the top
Select View Info

The URL will change to something like:

https://chat.example.com/yourteam/channels/abcdefghijklmnopqrstuvwxyz
                                            ^^^^^^^^^^^^^^^^^^^^^^^^^
                                            This is your Channel ID

Copy the Channel ID (the last part of the URL after /channels/)

Step 3: Get Server URL

Your server URL is the base URL of your Mattermost instance, for example:

https://chat.example.com
https://mattermost.company.com

Note: Do NOT include the team name or channel path - just the base URL.

Step 4: Required Information Summary

You'll need these during onboarding:

Field	Example	Where to Find
Server URL	`https://chat.example.com`	Your Mattermost instance URL
Bot Token	`ab12cd34ef56...`	Created in Step 1
Channel ID	`abc123xyz456...`	Found in Step 2
Bot Name	`claude-code`	The username you chose in Step 1

Optional: User Allowlist

If you want to restrict who can use the bot, prepare a comma-separated list of Mattermost usernames:

Example: alice,bob,charlie
Leave empty to allow everyone in the channel

Slack Setup

Quick Setup with App Manifest (Recommended)

Fastest way: Use the pre-configured app manifest to set up everything automatically.

Go to https://api.slack.com/apps
Click Create New App
Select From an app manifest
Choose your workspace
Paste the manifest from docs/slack-app-manifest.yaml:
- View it here: https://github.com/anneschuth/claude-threads/blob/main/docs/slack-app-manifest.yaml
- Or copy from your local installation: ~/.bun/install/global/node_modules/claude-threads/docs/slack-app-manifest.yaml
Click Create
Skip to Step 2 below (Socket Mode will already be configured)

Manual Setup (Alternative)

If you prefer to configure manually, follow these steps:

Step 1: Create a Slack App

Go to https://api.slack.com/apps
Click Create New App
Select From scratch
App Name: Choose a name (e.g., "Claude Code Bot")
Workspace: Select your workspace
Click Create App

Step 2: Enable Socket Mode

Socket Mode allows real-time communication without exposing a public URL.

In your app settings, go to Settings → Socket Mode (left sidebar)
Toggle Enable Socket Mode to ON
Click Generate an app-level token:
- Token Name: websocket-token (or any name you prefer)
- Scopes: Select connections:write
- Click Generate
⚠️ Copy the App-Level Token (starts with xapp-)
- You won't see this again!

Step 3: Configure OAuth Scopes

Go to Features → OAuth & Permissions (left sidebar)
Scroll to Scopes → Bot Token Scopes
Click Add an OAuth Scope and add these scopes:

Required scopes:
- channels:history - Read messages from public channels
- channels:read - View basic channel information
- chat:write - Send messages
- files:read - Access file content
- reactions:read - View emoji reactions
- reactions:write - Add/remove emoji reactions
- users:read - View users in the workspace

Step 4: Install App to Workspace

Scroll to the top of OAuth & Permissions page
Click Install to Workspace
Review permissions and click Allow
⚠️ Copy the Bot User OAuth Token (starts with xoxb-)
- This will be shown after installation
- You can also find it later under OAuth & Permissions → Bot User OAuth Token

Step 5: Subscribe to Events

Go to Features → Event Subscriptions (left sidebar)
Toggle Enable Events to ON
Scroll to Subscribe to bot events
Click Add Bot User Event and add:
- message.channels - Listen to messages in public channels
- reaction_added - Listen to emoji reactions being added
- reaction_removed - Listen to emoji reactions being removed
Click Save Changes

Finishing Steps (All Setup Methods)

Get Channel ID

Open Slack in your browser or desktop app
Right-click the channel where you want the bot to operate
Select View channel details
Scroll to the bottom
Copy the Channel ID (starts with C, e.g., C0123456789)

Alternative method:
- In the channel, click the channel name at the top
- The URL will show the channel ID:
```
https://app.slack.com/client/T123ABC/C0123456789
                                     ^^^^^^^^^^^
                                     Channel ID
```

Invite Bot to Channel

In Slack, go to the channel where you want the bot
Type /invite @your-bot-name (use the display name you chose)
Press Enter
The bot should join the channel

Required Information Summary

You'll need these during onboarding:

Field	Example	Where to Find
Bot User OAuth Token	`xoxb-123-456-...`	Step 4 (OAuth & Permissions)
App-Level Token	`xapp-1-A0123-...`	Step 2 (Socket Mode)
Channel ID	`C0123456789`	Step 6
Bot Name	`claude`	Your app's display name

Optional: User Allowlist

If you want to restrict who can use the bot, prepare a comma-separated list of Slack usernames (not display names):

Example: alice.smith,bob.jones,charlie.brown
To find a username: Click a user's profile → More → Copy member ID → Username is shown
Leave empty to allow everyone in the channel

Running the Onboarding

First Time Setup

Just run the tool - it will guide you:

# Install
bun install -g claude-threads

# Run the wizard
cd /your/project
claude-threads

The wizard will:

✅ Walk you through global settings (working directory, Chrome, git)
✅ Show you platform checklists (what you need before adding a platform)
✅ Guide you through adding Mattermost and/or Slack platforms
✅ Validate credentials in real-time and test permissions
✅ Show a configuration summary before saving

When prompted for platform credentials:

Use the Mattermost Setup or Slack Setup sections above to create your bot
The wizard will wait while you gather the required information
Come back and enter the credentials when ready

Multiple platforms:

You can connect to multiple Mattermost/Slack instances
Each platform gets a unique ID (e.g., mattermost-main, slack-eng)
Add platforms one at a time, or add more later with --setup

Reconfiguring

To modify your configuration:

claude-threads --setup

This will reload your existing config and let you update settings.

Manual Configuration (Advanced)

⚠️ Not recommended for first-time setup!

The interactive wizard (claude-threads) is the recommended way to configure claude-threads because it:

Validates your credentials in real-time

Provides helpful error messages and troubleshooting

Ensures correct YAML format

Tests bot permissions and channel access

Only edit manually if you:

Need to quickly update a token or setting

Are an experienced user comfortable with YAML

Have already run the wizard at least once

If you still want to manually edit the config:

# Config is stored at:
~/.config/claude-threads/config.yaml

# Edit with your favorite editor:
nano ~/.config/claude-threads/config.yaml

# Then restart claude-threads to apply changes

Reference config.yaml:

version: 2
workingDir: /home/user/projects
chrome: false
worktreeMode: prompt

platforms:
  # Mattermost
  - id: mattermost-main
    type: mattermost
    displayName: Main Team
    url: https://chat.example.com
    token: your-mattermost-token
    channelId: abc123xyz456
    botName: claude-code
    allowedUsers: []  # empty = allow everyone
    skipPermissions: false

  # Slack
  - id: slack-eng
    type: slack
    displayName: Engineering Team
    botToken: xoxb-your-bot-token
    appToken: xapp-your-app-token
    channelId: C0123456789
    botName: claude
    allowedUsers: []  # empty = allow everyone
    skipPermissions: false

Troubleshooting

Mattermost Issues

"Invalid token" or "401 Unauthorized"

Check that you copied the full token from the Bot Account creation page
Verify the token is for the correct Mattermost instance
Try creating a new bot account and token

"Cannot find channel" or "403 Forbidden"

Add the bot to the channel: Type @botname in the channel to invite it
Check the Channel ID is correct (from View Info)
Verify the bot has "Post:All" and "Post:Channels" permissions

Bot doesn't respond to messages

Check the bot name matches what you're @mentioning
Verify the bot is a member of the channel
Look at claude-threads logs for errors (DEBUG=1 claude-threads)

Slack Issues

"invalid_auth" or "token_revoked"

Regenerate tokens: Go to your app settings and reinstall the app
Check you're using the Bot User OAuth Token (not User OAuth Token)
Verify Socket Mode is enabled with a valid App-Level Token

"channel_not_found"

Invite the bot to the channel: /invite @your-bot-name
Check the Channel ID is correct (should start with C)
Verify the bot has channels:read and channels:history scopes

Bot doesn't respond to messages

Check Event Subscriptions are enabled with message.channels
Verify Socket Mode is enabled (required for receiving events)
Invite the bot to the channel if not already a member
Look at claude-threads logs (DEBUG=1 claude-threads)

"missing_scope" errors

Review OAuth scopes in Step 3 above
Reinstall the app after adding missing scopes
Required scopes: channels:history, channels:read, chat:write, files:read, reactions:read, reactions:write, users:read

General Issues

"Claude CLI not found"

Install Claude Code CLI: npm install -g @anthropic-ai/claude-code@2.0.76
Verify it's in PATH: which claude
Set custom path if needed: CLAUDE_PATH=/path/to/claude claude-threads

"Incompatible Claude CLI version"

Check your version: claude --version
Install compatible version: npm install -g @anthropic-ai/claude-code@2.0.76
Skip check (not recommended): claude-threads --skip-version-check

Can't find config file

Default location: ~/.config/claude-threads/config.yaml
Create directory: mkdir -p ~/.config/claude-threads
Run onboarding: claude-threads will create the config

Bot works but permissions don't prompt

Check skipPermissions is set to false in config
Restart claude-threads after changing config
Try !permissions interactive in a running session

Getting Help

If you're still stuck:

Check logs: Run with DEBUG=1 claude-threads for verbose output
Review the README: See CLAUDE.md for architecture details
Check the issues: https://github.com/anneschuth/claude-threads/issues
Open an issue: Include:
- Platform (Mattermost/Slack)
- Error messages from logs
- Steps to reproduce
- Your config (with tokens redacted!)

Next Steps

Once configured, test your bot:

Start claude-threads:
```
claude-threads
```

In your chat platform, @mention the bot:

@botname write "hello world" to test.txt

Watch the bot create a thread and stream Claude's response
Explore commands:
- !help - Show available commands
- !permissions interactive - Enable permission prompts
- !cd /path - Change working directory
- !stop - End the session

Happy coding with Claude! 🚀

FilesExpand file tree

SETUP_GUIDE.md

Latest commit

History

SETUP_GUIDE.md

File metadata and controls

claude-threads Setup Guide

Table of Contents

Mattermost Setup

Step 1: Create a Bot Account

Step 2: Get Channel ID

Step 3: Get Server URL

Step 4: Required Information Summary

Optional: User Allowlist

Slack Setup

Quick Setup with App Manifest (Recommended)

Manual Setup (Alternative)

Step 1: Create a Slack App

Step 2: Enable Socket Mode

Step 3: Configure OAuth Scopes

Step 4: Install App to Workspace

Step 5: Subscribe to Events

Finishing Steps (All Setup Methods)

Get Channel ID

Invite Bot to Channel

Required Information Summary

Optional: User Allowlist

Running the Onboarding

First Time Setup

Reconfiguring

Manual Configuration (Advanced)

Troubleshooting

Mattermost Issues

"Invalid token" or "401 Unauthorized"

"Cannot find channel" or "403 Forbidden"

Bot doesn't respond to messages

Slack Issues

"invalid_auth" or "token_revoked"

"channel_not_found"

Bot doesn't respond to messages

"missing_scope" errors

General Issues

"Claude CLI not found"

"Incompatible Claude CLI version"

Can't find config file

Bot works but permissions don't prompt

Getting Help

Next Steps