🗣️ Simulate realistic Slack conversations for testing and demos
Post realistic support conversations to Slack with proper formatting, threading, and reactions. Perfect for testing chat interfaces, training support teams, or populating demo workspaces.
- 📝 Rich text formatting - Bold, italic, code, links, and emoji support
- 🧵 Threaded conversations - Replies automatically grouped in threads
- 👍 Smart reactions - Auto-add reactions based on message content
- 🤖 AI message generation - Use Gemini 3 Flash to create realistic conversations
- 🐙 GitHub context - Generate messages from real commits, PRs, and issues
- 🎨 Beautiful terminal UI - Progress tracking with rich output
- 🐳 Docker ready - Easy deployment with container support
- ⚙️ Flexible configuration - CLI arguments and JSON message definitions
- ✅ Message validation - Schema validation with Pydantic
- 🔒 Multiple auth methods - Session tokens, User OAuth, or Bot tokens
- Python 3.13+ or Docker
- mise (recommended) or uv
- Slack workspace credentials (see Authentication)
You'll need Slack credentials to post messages. We support multiple authentication methods:
- Session Tokens (xoxc/xoxd) - Quick setup, browser-based (expires frequently)
- User OAuth Token (xoxp) - Recommended for production use
- Bot Token (xoxb) - For bot-based workflows
📖 See docs/usage.md for detailed setup instructions for each method.
Option 1: Install via pipx (recommended)
# Install globally with pipx
pipx install yap-on-slack
# Or install directly from GitHub
pipx install git+https://github.com/echohello-dev/yap-on-slack.git
# Initialize config files in current directory
yos init
# Edit .env with your credentials
# See docs/usage.md for how to obtain each value
nano .env
# Run with default messages
yos runOption 2: Install via pip
pip install yap-on-slack
# Or from GitHub
pip install git+https://github.com/echohello-dev/yap-on-slack.git
yos init && yos runOption 3: From source (development)
# Clone the repository
git clone https://github.com/echohello-dev/yap-on-slack.git
cd yap-on-slack
# Install dependencies
mise run install
# Run with mise
mise run runCLI Aliases: yos, yaponslack, yap-on-slack
# Initialize config files (.env, users.yaml, messages.json)
yos init
# Post default messages
yos run
# Use custom messages file
yos run --messages custom.json
# Generate messages with AI (requires OPENROUTER_API_KEY)
yos run --use-ai
# Dry run (validate without posting)
yos run --dry-run
# Limit messages and add delays
yos run --limit 5 --delay 3
# Verbose output for debugging
yos run --verbose
# Show version
yos --versionyos init - Initialize configuration files
--force, -f- Overwrite existing files
yos run - Post messages to Slack
--messages PATH- Custom messages JSON file--users PATH- Custom users YAML config--user NAME- Force specific user for all messages--use-ai- Generate messages using OpenRouter Gemini 3 Flash--dry-run- Validate without posting to Slack--limit N- Post only first N messages--delay SECONDS- Delay between messages (default: 2.0)--reply-delay SECONDS- Delay between replies (default: 1.0)--reaction-delay SECONDS- Delay before reactions (default: 0.5)--verbose, -v- Enable debug logging--debug-auth- Print safe diagnostics on auth failures
yos version - Show version information
Run yos --help or yos run --help for full options.
Generate realistic conversations using OpenRouter's Gemini 3 Flash model with optional GitHub context:
- Get an OpenRouter API key: https://openrouter.ai
- Add to
.env:OPENROUTER_API_KEY=sk-or-v1-your-key-here
- Optional: Add GitHub token for context:
GITHUB_TOKEN=ghp_your-token-here # Or use: gh auth token (if GitHub CLI installed) - Run with AI:
yos run --use-ai
When --use-ai is used:
- Fetches recent commits, PRs, and issues from your GitHub repositories
- Generates 20 realistic engineering team conversations
- Messages reference actual project context (repos, issues, PRs)
- Falls back to default messages if AI generation fails
Create messages.json with your conversation threads:
[
{
"text": "*Deploy complete* :rocket: New API version is live!",
"replies": [
"Nice! Performance looks good",
"All tests passing :white_check_mark:"
]
},
{
"text": "Quick question - what's our policy on log retention?"
}
]Supported formatting: bold, italic, strikethrough, code, links, emoji, and bullet points.
📖 See docs/usage.md for complete formatting syntax and examples.
# Build and run locally
docker build -t yap-on-slack .
docker run --rm --env-file .env yap-on-slack
# Or use pre-built image from GitHub Container Registry
docker pull ghcr.io/echohello-dev/yap-on-slack:latest
docker run --rm --env-file .env ghcr.io/echohello-dev/yap-on-slack:latest# Install dependencies (including dev tools)
mise run install
# Install pre-commit hooks
uv run pre-commit installmise run lint # Run ruff linter
mise run format # Format code with ruff
mise run typecheck # Run mypy type checking
mise run test # Run pytest
mise run check # Run all checks (lint + typecheck + test)See all available tasks: mise tasks
We welcome contributions! Please see CONTRIBUTING.md for:
- Development setup
- Code style guidelines
- Testing procedures
- Pull request process
- docs/usage.md - Comprehensive usage guide, authentication setup, and troubleshooting
- SECURITY.md - Security best practices and token management
- CONTRIBUTING.md - Development guidelines and workflow
- docs/adrs/ - Architecture decision records
- Build Workflow - Automated linting, type checking, testing, and Docker image publishing
- Release Please - Semantic versioning and automated changelog generation
Docker images: ghcr.io/echohello-dev/yap-on-slack
MIT - See LICENSE for details