slack-context-search

A CLI tool to search Slack channel history and generate context documents. Perfect for gathering historical context on features, bugs, and discussions to feed into AI assistants like Claude, GPT, or Cursor.

Why?

When working on complex features or debugging issues, historical Slack discussions often contain crucial context:

• Why certain decisions were made
• Previous attempts and their outcomes
• Customer feedback and pain points
• Related issues and workarounds

This tool helps you extract that knowledge and format it for AI assistants.

Installation

# Install globally
npm install -g slack-context-search

# Or use with npx
npx slack-context-search --help

# Or with pnpm
pnpm add -g slack-context-search

Quick Start

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name it (e.g., "Context Search Bot")
4. Select your workspace

2. Add Bot Token Scopes

In OAuth & Permissions → Bot Token Scopes, add:

| Scope | Purpose | |-------|---------| | channels:history | Read public channel messages | | channels:read | List public channels | | groups:history | Read private channel messages | | groups:read | List private channels | | users:read | Resolve user names |

3. Install App & Get Token

1. Click Install to Workspace
2. Authorize the app
3. Copy the Bot User OAuth Token (starts with xoxb-)

4. Invite Bot to Channels

For each channel you want to search:

/invite @YourBotName

5. Set Environment Variable

export SLACK_BOT_TOKEN=xoxb-your-token-here

Usage

List Accessible Channels

slack-search channels

Search for Keywords

# Basic search (OR logic between keywords)
slack-search search authentication login

# Search specific channels
slack-search search bug --channels engineering,support

# Include thread replies
slack-search search "payment failed" --threads

# Save to markdown file
slack-search search refactor --output results.md

# Last 30 days only
slack-search search deployment --days 30

# Output as JSON
slack-search search api --format json

Generate Analysis Document

# Analyze a topic and generate a markdown summary
slack-search analyze "authentication system" --output auth-analysis.md

Examples

Gathering Context for a Bug Fix

# Search for discussions about a specific bug
slack-search search "checkout timeout" "payment error" \
  --channels bugs,support,engineering \
  --threads \
  --days 90 \
  --output checkout-bugs-context.md

Understanding a Feature's History

# Analyze discussions about a feature
slack-search analyze "user permissions" \
  --days 180 \
  --output permissions-context.md

Feeding Context to AI

# Generate context file
slack-search analyze "API rate limiting" --output context.md

# Then in your AI assistant:
# "Read context.md and summarize the main issues with rate limiting"

Programmatic Usage

You can also use this as a library:

import { SlackSearchClient, formatAsMarkdown } from 'slack-context-search';

const client = new SlackSearchClient(process.env.SLACK_BOT_TOKEN);

const result = await client.search({
  keywords: ['authentication', 'login'],
  channels: ['engineering'],
  includeThreads: true,
  limit: 500,
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // Last 30 days
});

const markdown = formatAsMarkdown(result, 'Authentication Analysis');
console.log(markdown);

Output Formats

Console (default)

Colored terminal output, truncated for readability.

Markdown

Structured document grouped by date with formatted messages:

# Search: authentication

> **Channels searched:** engineering, support
> **Total messages found:** 42
> **Generated:** 2026-01-19T10:30:00.000Z

---

## 2026-01-18

### [14:30] #engineering [3 replies]

> We should consider implementing OAuth2 for the new auth flow.
> The current session-based approach has scaling issues.

JSON

Raw data for further processing or integration with other tools.

Limitations

1. No Search API - Slack's search.messages API requires Enterprise Grid. This tool uses conversations.history which works on all plans but requires bot membership in channels.

2. Rate Limits - Slack has rate limits. The tool handles basic pagination but may slow down for very large searches.

3. Bot Access - Bot must be explicitly invited to each channel you want to search.

Troubleshooting

"No channels to search"

Invite the bot to channels first:

/invite @YourBotName

"not_allowed_token_type"

You're using a User Token scope (like search:read) with a Bot Token. This tool only works with Bot Tokens.

Empty Results

• Verify keywords are spelled correctly
• Check the bot is a member of target channels
• Try a broader date range with --days

Contributing

Contributions are welcome! Please open an issue or PR.

License

MIT