Slack LLM Runner 🤖

Run CLI tools (Claude Code, Kimi, shell commands) from Slack with smart output filtering and full session logging.

✨ What It Does

Slack CLI Wrapper is a bidirectional bridge between Slack and CLI tools running on your local machine. It lets you:

🚀 Execute commands from Slack: run: docker ps, claude: refactor auth.js, kimi: explain this code
💬 Interact with AI CLIs - Have full conversations with Claude Code or Kimi through Slack threads
📊 Run scheduled jobs - Cron jobs that execute commands and report to Slack
📁 Access full logs - Complete session output is always logged locally, retrievable on demand
🧠 Smart filtering - AI CLIs use "envelope" markers to decide what gets posted to Slack (no noise!)

Demo

[Slack #dev-channel]

Alice:  claude: write tests for utils.js

Bot:    🚀 Session started (claude code) — logs: session_abc123.log

        [Claude reads files, writes tests, runs them — 
         ~200 lines of output goes to log file only]

Bot:    ✅ Refactor complete. All 47 tests pass.
        Coverage: 94% on utils.js.

Bot:    ✅ Session complete (exit code 0)

Alice:  /logs
Bot:    📎 session_abc123.log (2.1 KB uploaded)

🏗️ Architecture Overview

┌─────────────┐     WebSocket      ┌─────────────────────────────────────────────┐
│   Slack     │◀══════════════════▶│  Slack CLI Wrapper (Node.js)               │
│  (Cloud)    │    (Socket Mode)   │                                             │
└─────────────┘                    │  ┌─────────────┐    ┌───────────────────┐  │
                                   │  │   Slack     │    │   CLI Runner      │  │
                                   │  │  Listener   │───▶│   (node-pty)      │  │
                                   │  │  (Bolt)     │◀───│                   │  │
                                   │  └─────────────┘    └─────────┬─────────┘  │
                                   │                               │            │
                                   │                    ┌──────────┴─────────┐   │
                                   │                    ▼                    ▼   │
                                   │           ┌─────────────┐      ┌──────────┐ │
                                   │           │  Envelope   │      │  Full    │ │
                                   │           │  Parser     │      │ Output   │ │
                                   │           │  (LLM mode) │      │ Streamer │ │
                                   │           └──────┬──────┘      └────┬─────┘ │
                                   │                  │                   │      │
                                   │         ┌────────▼────────┐  ┌───────▼────┐ │
                                   │         │     Slack       │  │   Slack    │ │
                                   │         │   (enveloped)   │  │  (all out) │ │
                                   │         └─────────────────┘  └────────────┘ │
                                   └─────────────────────────────────────────────┘

Two-Track Output Model:

Track 1: Log → Everything is written to logs/sessions/<sessionId>.log
Track 2: Slack → AI CLIs use envelope markers; shell commands stream everything

🚀 Quick Start

Prerequisites

Node.js 20+
A Slack workspace where you can create apps
Bash shell (Windows: Git Bash or WSL)
(Optional) claude CLI or kimi CLI for AI features

1. Clone & Install

git clone https://github.com/yourusername/slack-cli-wrapper.git
cd slack-cli-wrapper
npm install

2. Create Slack App

Go to api.slack.com/apps → Create New App
Enable Socket Mode (toggle ON)
Generate an App-Level Token with scope connections:write
Add Bot Token Scopes: chat:write, channels:read, users:read
Subscribe to Bot Events: message.channels
Install to Workspace

3. Configure Environment

cp .env.example .env

Edit .env:

SLACK_APP_TOKEN=xapp-...            # From step 2
SLACK_BOT_TOKEN=xoxb-...            # From step 2
SLACK_LISTEN_CHANNELS=C0123456789   # Channel ID(s) to listen in
ALLOWED_USER_IDS=U0123456789        # Your Slack user ID

4. Configure Commands

Edit config/commands.yaml:

commands:
  - prefix: "run"
    binary: "bash"
    args: ["-c"]
    mode: one-shot
    envelope: false
    description: "Run a shell command"

  - prefix: "claude"
    binary: "claude"          # or full path
    args: ["--verbose"]
    promptFlag: "-p"
    sessionIdFlag: "--session-id"  # Create new session
    resumeFlag: "--resume"         # Continue existing session
    mode: one-shot
    envelope: true
    description: "Run Claude Code"

5. Run

npm run dev        # Development with hot reload
# or
npm run build      # Build for production
npm start          # Run production build

💬 Usage

Shell Commands (Full Output)

run: docker ps
run: npm test
run: ls -la

Output streams directly to Slack in real-time.

AI CLI Sessions (Envelope Filtered)

claude: refactor the auth module
kimi: explain this regex

The AI sees a system prompt that teaches it to use envelope markers:

<<<SLACK:progress>>>
Analyzed auth module. Found 3 functions to refactor.
<<<END_SLACK>>>

Only enveloped messages appear in Slack. Full output is in the log.

Thread Follow-Ups & Session Continuation

Reply in the thread to continue the conversation with context preserved:

Alice: claude: my name is Alice
Bot:   🚀 Session started — Run Claude Code
       ✅ Session complete (exit code 0)

Alice [in thread]: what is my name?
      → Spawns continuation with --resume, Claude remembers "Alice"

How it works:

Kimi: Uses -S <session-id> flag (same for create and resume)
Claude: Uses --session-id <uuid> for first call, --resume <uuid> for follow-ups
Session IDs: Deterministically generated from slack-<channel>-<thread> so same thread always maps to same session

Control Commands

Command	Description
`/status`	List active sessions
`/stop <id>`	Kill a session
`/logs`	Upload most recent session log
`/logs <id>`	Upload specific session log
`/logs tail 50`	Show last 50 lines
`/logs list`	List recent sessions
`/help`	Show available commands

⚙️ Configuration

Environment Variables

Variable	Description
`SLACK_APP_TOKEN`	Socket Mode connection token (`xapp-...`)
`SLACK_BOT_TOKEN`	Web API token (`xoxb-...`)
`SLACK_LISTEN_CHANNELS`	Comma-separated channel IDs
`ALLOWED_USER_IDS`	Comma-separated user IDs allowed to run commands
`SESSION_TIMEOUT_MINUTES`	Max session lifetime (default: 30)
`OUTPUT_FLUSH_INTERVAL_MS`	How often to push output (default: 2000)
`ENVELOPE_ACTIVATION_DELAY_MS`	Delay before parsing envelopes (default: 1500)

Authorization (`config/authorization.yaml`)

rules:
  - channels: ["C0123456789"]
    users: ["*"]                    # Any user in ALLOWED_USER_IDS
    allowed_prefixes: ["claude", "kimi", "run"]

  - channels: ["C9876543210"]
    users: ["U0123456789"]          # Only specific user
    allowed_prefixes: ["run"]       # Only shell commands

Scheduled Jobs (`config/jobs.yaml`)

jobs:
  - name: "daily-backup-check"
    cron: "0 6 * * *"
    command: "bash scripts/backup-check.sh"
    channel: "C0123456789"
    cwd: "/path/to/project"

🔧 Development

Project Structure

slack-cli-wrapper/
├── src/
│   ├── cli/              # PTY spawn, session lifecycle
│   ├── commands/         # Command parsing & routing
│   ├── streaming/        # Envelope parser, streamer, log writer
│   ├── scheduler/        # Cron job scheduling
│   ├── security/         # Authorization & command filtering
│   ├── slack/            # Bolt app, listeners, reporter
│   └── utils/            # Config, logger, formatting
├── config/
│   ├── prompts/          # System prompts for LLMs
│   ├── authorization.yaml
│   ├── commands.yaml
│   └── jobs.yaml
├── scripts/debug/        # Manual debugging utilities
└── test/                 # Automated tests

Scripts

npm run dev              # Development mode
npm run build            # Compile TypeScript
npm start                # Production mode
npm test                 # Run unit tests
npm run test:lifecycle   # Run E2E session lifecycle tests
npm run restart          # Kill all node processes and restart

Running Tests

# Unit tests for process handle
npm test

# E2E tests for session lifecycle
npm run test:lifecycle

# Integration test
node --import tsx --test test/integration.test.ts

🔒 Security

No tokens in code - All secrets in .env (gitignored)
User allowlist - Only configured Slack users can run commands
Channel restriction - Bot only listens in configured channels
Command filtering - Block dangerous patterns (rm -rf, etc.)
Audit logging - Every command logged with user ID, timestamp, exit code
Session timeouts - Prevent runaway processes

Security Best Practices

Keep .env file secure and never commit it
Use specific user IDs in ALLOWED_USER_IDS, not *
Restrict allowed_prefixes per channel as needed
Review audit logs regularly: logs/audit.log
Run with minimal permissions (don't run as root)

🤝 Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/slack-cli-wrapper.git
cd slack-cli-wrapper

# Install dependencies
npm install

# Copy env template
cp .env.example .env
# Edit .env with your test Slack app tokens

# Run in dev mode
npm run dev

Contribution Guidelines

Fork the repository
Create a branch for your feature: git checkout -b feature/amazing-feature
Make your changes with clear, focused commits
Add tests if applicable
Update documentation if needed
Submit a Pull Request with a clear description

Code Style

TypeScript with strict mode enabled
Use meaningful variable names
Add JSDoc comments for public APIs
Keep functions focused and small
Handle errors gracefully

Areas for Contribution

📚 Documentation

Architecture Guide - Detailed system design
Setup Guide - Step-by-step setup instructions
Process Management - Handling orphaned processes

🐛 Troubleshooting

Bot won't connect

# Kill all node processes
npm run clean

# Wait 30 seconds for Slack to release connection
# Then restart
npm run dev

No output from commands

Check that bash.exe is in your PATH (Windows)
Verify session logs: logs/sessions/*.log
Run E2E tests: npm run test:lifecycle

Socket Mode disconnects

Slack only allows one connection per app token. If you have multiple instances running:

Kill all node processes: npm run clean
Wait 30 seconds
Restart the bot

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with Slack Bolt framework
Uses node-pty for PTY support
Inspired by the need for less noisy AI CLI integrations

Made with ❤️ for cleaner Slack integrations

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
config		config
docs		docs
scripts		scripts
src		src
test		test
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.versionrc.json		.versionrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Slack LLM Runner 🤖

✨ What It Does

Demo

🏗️ Architecture Overview

🚀 Quick Start

Prerequisites

1. Clone & Install

2. Create Slack App

3. Configure Environment

4. Configure Commands

5. Run

💬 Usage

Shell Commands (Full Output)

AI CLI Sessions (Envelope Filtered)

Thread Follow-Ups & Session Continuation

Control Commands

⚙️ Configuration

Environment Variables

Authorization (config/authorization.yaml)

Scheduled Jobs (config/jobs.yaml)

🔧 Development

Project Structure

Scripts

Running Tests

🔒 Security

Security Best Practices

🤝 Contributing

Development Setup

Contribution Guidelines

Code Style

Areas for Contribution

📚 Documentation

🐛 Troubleshooting

Bot won't connect

No output from commands

Socket Mode disconnects

📄 License

🙏 Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Authorization (`config/authorization.yaml`)

Scheduled Jobs (`config/jobs.yaml`)

Packages