relaybot 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# RelayBot
+
+A Slack-to-AI gateway that lets you interact with Claude/Codex directly from your DMs.
+
+---
+
+## What is RelayBot?
+
+RelayBot acts as a bridge between Slack and AI coding agents, allowing you to interact with Claude or Codex through simple Slack DMs. Instead of switching between tools, you can request code changes, ask questions, and manage development tasks without leaving Slack.
+
+### Key Features
+
+- **Conversational AI Access** — Chat with Claude or Codex directly from Slack DMs
+- **Code Execution** — AI can read, write, and modify code in your projects
+- **Task Automation** — Request file changes, refactoring, bug fixes, or new features
+- **Context-Aware Responses** — Maintains project directory context across conversations
+- **Summarized Replies** — Long AI outputs are condensed into concise, actionable messages
+- **Persistent Sessions** — AI session stays alive between messages, preserving context
+
+### Use Cases
+
+- **Quick Code Changes** — "Add a loading spinner to the login button"
+- **Code Review** — "Review the latest PR and suggest improvements"
+- **Bug Investigation** — "Why is the checkout flow failing for guest users?"
+- **Refactoring** — "Refactor the authentication module to use async/await"
+- **Documentation** — "Generate API docs for the user service"
+- **Learning** — "Explain how the caching layer works in this codebase"
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           SLACK                                     │
+│  ┌──────────┐                                    ┌──────────────┐   │
+│  │   User   │ ───── sends message ─────────────► │   Channel/   │   │
+│  │          │ ◄──── receives reply ───────────── │      DM      │   │
+│  └──────────┘                                    └──────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+                              │ ▲
+                              │ │
+              Slack WebSocket │ │ Slack Sender
+              (Socket Mode)   │ │
+                              ▼ │
+┌─────────────────────────────────────────────────────────────────────┐
+│                            RELAYBOT                                 │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                    Slack Listener                              │ │
+│  │                  (Socket Mode Connection)                      │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                              │                                      │
+│                              │ forwards message                     │
+│                              ▼                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                     PTY Bridge                                 │ │
+│  │              Spawns persistent AI CLI process                  │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              │ stdin/stdout
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      CLAUDE / CODEX CLI                             │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                    AI Agent Session                            │ │
+│  │         • Processes user requests                              │ │
+│  │         • Executes tasks (code, commands, etc.)                │ │
+│  │         • Maintains project context                            │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                              │                                      │
+│                              │ summarizes response                  │
+│                              ▼                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                   Response Summarizer                          │ │
+│  │      • Condenses long outputs to concise messages              │ │
+│  │      • Includes relevant links (PRs, docs, etc.)               │ │
+│  │      • Sends reply back to Slack                               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## How It Works
+
+1. **Slack Connection** — RelayBot connects to Slack via WebSocket (Socket Mode) and listens for DMs
+2. **Message Reception** — When you send a message, Slack forwards it to RelayBot
+3. **AI Bridge** — RelayBot spawns a persistent Claude or Codex CLI session and forwards your message
+4. **AI Processing** — The AI processes your request with full access to your codebase
+5. **Response Summarization** — Long outputs are summarized into concise, actionable messages
+6. **Slack Reply** — The summarized response is sent back to you via Slack DM
+
+---
+
+## Installation
+
+```bash
+npm install -g slack-relaybot
+```
+
+## Quick Start
+
+```bash
+# 1. Run setup to configure Slack credentials
+relaybot-setup
+
+# 2. Start the bot with Claude
+relaybot
+
+# Or start with Codex
+relaybot --codex
+```
+
+---
+
+## Setup
+
+Before running the bot, you need to configure your Slack credentials.
+
+### Interactive Setup
+
+Run the setup command and follow the prompts:
+
+```bash
+relaybot-setup
+```
+
+You will be asked for:
+- **SLACK_BOT_TOKEN** - Bot User OAuth Token (starts with `xoxb-`)
+- **SLACK_APP_TOKEN** - App-Level Token (starts with `xapp-`)
+- **SLACK_USER_ID** - Your Slack User ID (starts with `U`)
+- **WORKING_DIR** - Directory where the AI will operate
+
+### Manual Setup
+
+Alternatively, create the config file manually at `~/.relaybot/config.conf`:
+
+```bash
+mkdir -p ~/.relaybot
+```
+
+Then create `~/.relaybot/config.conf`:
+
+```
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_APP_TOKEN=xapp-your-app-token
+SLACK_USER_ID=U0XXXXXXXX
+WORKING_DIR=/path/to/directory
+```
+
+### Creating a Slack App
+
+If you don't have a Slack app yet, follow these steps:
+
+#### 1. Create the App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App**
+3. Choose **From scratch**
+4. Enter an app name (e.g., "RelayBot") and select your workspace
+5. Click **Create App**
+
+#### 2. Enable Socket Mode
+
+Socket Mode allows the bot to receive events via WebSocket instead of HTTP endpoints.
+
+1. Go to **Socket Mode** in the left sidebar
+2. Toggle **Enable Socket Mode** to ON
+3. You'll be prompted to create an App-Level Token:
+   - Token Name: `socket-token` (or any name)
+   - Scope: `connections:write`
+   - Click **Generate**
+4. Copy the token (starts with `xapp-`) — this is your **SLACK_APP_TOKEN**
+
+#### 3. Configure Bot Permissions
+
+1. Go to **OAuth & Permissions** in the left sidebar
+2. Scroll to **Scopes** → **Bot Token Scopes**
+3. Add these scopes:
+   - `chat:write` — Send messages
+   - `im:history` — Read DM history
+   - `im:read` — View DM metadata
+   - `im:write` — Start DMs with users
+   - `users:read` — View user info
+
+#### 4. Enable Event Subscriptions
+
+1. Go to **Event Subscriptions** in the left sidebar
+2. Toggle **Enable Events** to ON
+3. Expand **Subscribe to bot events**
+4. Add these events:
+   - `message.im` — Receive DM messages
+
+#### 5. Install the App
+
+1. Go to **Install App** in the left sidebar
+2. Click **Install to Workspace**
+3. Review permissions and click **Allow**
+4. Copy the **Bot User OAuth Token** (starts with `xoxb-`) — this is your **SLACK_BOT_TOKEN**
+
+#### 6. Get Your User ID
+
+1. Open Slack
+2. Click on your profile picture → **Profile**
+3. Click the **⋮** (more) button
+4. Click **Copy member ID** — this is your **SLACK_USER_ID**
+
+### Summary of Tokens
+
+| Token | Where to Find | Format |
+|-------|---------------|--------|
+| `SLACK_BOT_TOKEN` | OAuth & Permissions → Bot User OAuth Token | `xoxb-...` |
+| `SLACK_APP_TOKEN` | Basic Information → App-Level Tokens | `xapp-...` |
+| `SLACK_USER_ID` | Slack Profile → Copy member ID | `U0XXXXXXXX` |
+
+---
+
+## Requirements
+
+- **Node.js** v14+
+- **Claude CLI** or **Codex CLI** available on PATH
+
+---
+
+## Configuration
+
+Configuration is stored in `~/.relaybot/config.conf`.
+
+| Variable | Description |
+|----------|-------------|
+| `SLACK_BOT_TOKEN` | Slack Bot OAuth token (`xoxb-...`) |
+| `SLACK_APP_TOKEN` | Slack App-level token for Socket Mode (`xapp-...`) |
+| `SLACK_USER_ID` | Your Slack User ID (`U0XXXXXXXX`) |
+| `WORKING_DIR` | Directory where the AI will operate |

package/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function showHelp() {
+  console.log(`
+🤖 RelayBot - Slack-to-AI gateway
+
+Usage: relaybot <command>
+
+Commands:
+  setup    Configure Slack credentials and working directory
+  start    Start the RelayBot server
+
+Examples:
+  relaybot setup    # Run interactive setup
+  relaybot start    # Start the bot
+`);
+}
+
+switch (command) {
+  case 'setup':
+    require('./setup');
+    break;
+  case 'start':
+    require('./main');
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    showHelp();
+    process.exit(1);
+}

package/config.conf.example

@@ -0,0 +1,4 @@
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_APP_TOKEN=xapp-your-app-token
+SLACK_USER_ID=U0XXXXXXXX
+WORKING_DIR=/path/to/directory

package/main.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+const { App } = require('@slack/bolt');
+const loadConfig = require('./src/load-config');
+const agent = require('./src/agent');
+const slackHandlers = require('./src/slack-handlers');
+
+const config = loadConfig();
+
+if (!config || !config.SLACK_BOT_TOKEN || !config.SLACK_APP_TOKEN || !config.SLACK_USER_ID) {
+  console.error('❌ Configuration not found or incomplete.\n');
+  console.log('Please run setup first:\n');
+  console.log('  relaybot setup\n');
+  process.exit(1);
+}
+
+const app = new App({
+  token: config.SLACK_BOT_TOKEN,
+  appToken: config.SLACK_APP_TOKEN,
+  socketMode: true
+});
+
+slackHandlers.registerHandlers(app);
+
+(async () => {
+  await app.start();
+  console.log('⚡️ RelayBot running (Socket Mode)');
+  agent.start();
+})();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "relaybot",
+  "version": "1.0.0",
+  "description": "A Slack-to-AI gateway that lets you interact with Claude/Codex directly from your DMs",
+  "main": "main.js",
+  "bin": {
+    "relaybot": "./cli.js"
+  },
+  "scripts": {
+    "start": "node main.js",
+    "setup": "node setup.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "slack",
+    "claude",
+    "codex",
+    "ai",
+    "chatbot",
+    "automation"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.3",
+    "@slack/bolt": "^4.6.0",
+    "@slack/web-api": "^7.13.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/setup.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const CONFIG_DIR = path.join(os.homedir(), '.relaybot');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.conf');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(prompt) {
+  return new Promise(resolve => rl.question(prompt, resolve));
+}
+
+async function setup() {
+  console.log('\n🤖 RelayBot Setup\n');
+  console.log('Please provide your Slack credentials.\n');
+
+  const botToken = await question('SLACK_BOT_TOKEN (xoxb-...): ');
+  const appToken = await question('SLACK_APP_TOKEN (xapp-...): ');
+  const userId = await question('SLACK_USER_ID (U0XXXXXXXX): ');
+
+  console.log('\nWorking directory (folder where the AI will operate).\n');
+  const workingDir = await question('WORKING_DIR: ');
+
+  const configLines = [
+    `SLACK_BOT_TOKEN=${botToken.trim()}`,
+    `SLACK_APP_TOKEN=${appToken.trim()}`,
+    `SLACK_USER_ID=${userId.trim()}`,
+    `WORKING_DIR=${workingDir.trim()}`
+  ];
+
+  // Create config directory if it doesn't exist
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  fs.writeFileSync(CONFIG_PATH, configLines.join('\n') + '\n');
+  console.log(`\n✅ Configuration saved to ${CONFIG_PATH}\n`);
+
+  rl.close();
+}
+
+setup().catch(err => {
+  console.error('Setup failed:', err.message);
+  rl.close();
+  process.exit(1);
+});

package/skills/relay-bot/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: relay-bot
+description: "Workspace-aware assistant that maintains project directory context and sends a Slack DM reply after completing a task or answering a question."
+---
+
+# RelayBot
+
+## Overview
+
+Maintain working-directory context for projects and send a Slack DM after tasks or answers using `send-slack-message.js`.
+
+## Working directory
+
+The working directory where the AI operates is configured in `~/.relaybot/config.conf`:
+
+```
+WORKING_DIR=/path/to/directory
+```
+
+## Workflow
+
+### 1) Resolve project context
+
+- Use the directory configured in `WORKING_DIR` as the working context.
+- Run all commands and file operations within this directory.
+- Avoid asking the user for clarification; pick the best default and proceed automatically.
+- If a question is truly required to continue, send it as a Slack DM using the script, then wait for the user's response via the Slack socket before proceeding.
+
+### 2) Execute the task in the active project
+
+- Run commands and edit files in the resolved working directory.
+- Keep the project context for follow-up requests unless the user switches again.
+
+### 3) Send a Slack DM reply after completion
+
+Run from this repo root:
+
+```bash
+node ./src/send-slack-message.js "Your message here"
+```
+
+## Output rules
+
+- Keep messages concise and actionable
+- Include relevant links (PR URLs, documentation, etc.)
+- For long answers, summarize key points
+
+## Notes
+
+- The script posts to the configured DM user in `~/.relaybot/config.conf`
+- The Slack bot token must be configured in `~/.relaybot/config.conf`

package/src/agent.js

@@ -0,0 +1,59 @@
+const pty = require('@lydell/node-pty');
+
+let claudeProcess = null;
+const useCodex = process.argv.includes('--codex');
+const shell = useCodex ? 'codex' : 'claude';
+
+function sendCommand(text) {
+  if (claudeProcess) {
+    setTimeout(() => {
+      claudeProcess.write(text + '\r\n');
+      claudeProcess.write('\x0D');
+    }, 500);
+  }
+}
+
+function isRunning() {
+  return claudeProcess !== null;
+}
+
+function start() {
+  claudeProcess = pty.spawn(shell, useCodex ? ['--yolo'] : ['--dangerously-skip-permissions'], {
+    name: 'xterm-color',
+    cols: 80,
+    rows: 30,
+    cwd: process.cwd(),
+    env: { ...process.env, TERM: process.env.TERM || 'xterm-256color' }
+  });
+
+  console.log(`--- Persistent ${useCodex ? 'Codex' : 'Claude'} Session Started ---`);
+
+  claudeProcess.onData((data) => {
+    const dataStr = data.toString();
+    const byPassPrompts = ['Do you want to proceed?'];
+    if (byPassPrompts.some((prompt) => dataStr.includes(prompt))) {
+      setTimeout(() => {
+        claudeProcess.write('\r\n');
+        claudeProcess.write('\x0D');
+      }, 500);
+    }
+
+    // Respond to cursor position queries from Codex to avoid CPR timeouts.
+    if (data.includes('\x1b[6n')) {
+      const occurrences = data.split('\x1b[6n').length - 1;
+      for (let i = 0; i < occurrences; i += 1) {
+        claudeProcess.write('\x1b[1;1R');
+      }
+      data = data.replace(/\x1b\[6n/g, '');
+    }
+    process.stdout.write(data);
+  });
+
+  return claudeProcess;
+}
+
+module.exports = {
+  sendCommand,
+  isRunning,
+  start
+};

package/src/delete-slack-message.js

@@ -0,0 +1,137 @@
+const { WebClient } = require('@slack/web-api');
+const loadConfig = require('./load-config');
+
+const config = loadConfig();
+
+if (!config || !config.SLACK_BOT_TOKEN) {
+  console.error('❌ Configuration not found. Run: node setup.js');
+  process.exit(1);
+}
+
+const DEFAULT_LOOKBACK_DAYS = 30;
+const token = config.SLACK_BOT_TOKEN;
+const web = new WebClient(token);
+
+function usage() {
+  console.log('Usage: node delete-slack-message.js <userId> [--bot-user-id <U...>] [--bot-id <B...>] [--app-id <A...>] [--oldest <ts>] [--latest <ts>]');
+  console.log('Example: node delete-slack-message.js U02N0ACQG6L --app-id A04MYMXDTA4');
+}
+
+function parseArgs(argv) {
+  const [, , userId, ...rest] = argv;
+  if (!userId) return null;
+  const args = { userId };
+  for (let i = 0; i < rest.length; i += 1) {
+    const key = rest[i];
+    const value = rest[i + 1];
+    if (!value) continue;
+    if (key === '--bot-user-id') args.botUserId = value;
+    if (key === '--bot-id') args.botId = value;
+    if (key === '--app-id') args.appId = value;
+    if (key === '--oldest') args.oldest = value;
+    if (key === '--latest') args.latest = value;
+  }
+  return args;
+}
+
+function resolveTimeBounds(oldest, latest) {
+  const now = Date.now();
+  const oldestMs = oldest ? Math.floor(Number(oldest) * 1000) : now - DEFAULT_LOOKBACK_DAYS * 24 * 60 * 60 * 1000;
+  const latestMs = latest ? Math.floor(Number(latest) * 1000) : now;
+  return {
+    oldest: (oldestMs / 1000).toString(),
+    latest: (latestMs / 1000).toString()
+  };
+}
+
+function isMatch(message, botUserId, botId, appId) {
+  if (!message) return false;
+  if (botUserId && message.user === botUserId) return true;
+  if (botId) {
+    if (message.bot_id === botId) return true;
+    if (message.bot_profile && message.bot_profile.id === botId) return true;
+  }
+  if (appId) {
+    if (message.app_id === appId) return true;
+    if (message.bot_profile && message.bot_profile.app_id === appId) return true;
+  }
+  return false;
+}
+
+async function getImChannelId(userId) {
+  const result = await web.conversations.open({ users: userId, return_im: true });
+  if (!result || !result.channel || !result.channel.id) {
+    throw new Error(`Unable to open DM with user ${userId}`);
+  }
+  return result.channel.id;
+}
+
+async function findLatestBotMessage(channelId, botUserId, botId, appId, oldest, latest) {
+  let cursor;
+  while (true) {
+    const result = await web.conversations.history({
+      channel: channelId,
+      oldest,
+      latest,
+      limit: 200,
+      cursor
+    });
+
+    const messages = result.messages || [];
+    for (const message of messages) {
+      if (isMatch(message, botUserId, botId, appId)) {
+        return message;
+      }
+    }
+
+    const nextCursor = result.response_metadata ? result.response_metadata.next_cursor : null;
+    if (!nextCursor) break;
+    cursor = nextCursor;
+  }
+
+  return null;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args) {
+    usage();
+    process.exit(1);
+  }
+
+  if (!token) {
+    throw new Error('SLACK_BOT_TOKEN is not set in config.conf');
+  }
+
+  if (!args.botUserId && !args.botId && !args.appId) {
+    const auth = await web.auth.test();
+    if (auth && auth.user_id) {
+      args.botUserId = auth.user_id;
+    }
+    if (auth && auth.bot_id) {
+      args.botId = auth.bot_id;
+    }
+    if (!args.botUserId && !args.botId && !args.appId) {
+      throw new Error('Missing identifiers. Provide --bot-user-id, --bot-id, or --app-id.');
+    }
+  }
+
+  const { oldest, latest } = resolveTimeBounds(args.oldest, args.latest);
+  const channelId = await getImChannelId(args.userId);
+  const message = await findLatestBotMessage(channelId, args.botUserId, args.botId, args.appId, oldest, latest);
+
+  if (!message) {
+    console.log(`No message found for bot ${args.botId} in DM with ${args.userId}.`);
+    return;
+  }
+
+  console.log(`Found message ${message.ts} in channel ${channelId}.`);
+
+  await web.chat.delete({ channel: channelId, ts: message.ts });
+  console.log(`Deleted message ${message.ts} in channel ${channelId}.`);
+}
+
+main().catch(error => {
+  console.error(`Failed to delete message: ${error.message}`);
+  process.exit(1);
+});

package/src/load-config.js

@@ -0,0 +1,31 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.relaybot');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.conf');
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(CONFIG_PATH, 'utf-8');
+  const config = {};
+
+  content.split('\n').forEach(line => {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const [key, ...valueParts] = trimmed.split('=');
+      if (key && valueParts.length > 0) {
+        config[key.trim()] = valueParts.join('=').trim();
+      }
+    }
+  });
+
+  return config;
+}
+
+module.exports = loadConfig;
+module.exports.CONFIG_DIR = CONFIG_DIR;
+module.exports.CONFIG_PATH = CONFIG_PATH;

package/src/send-slack-message.js

@@ -0,0 +1,33 @@
+const { WebClient } = require('@slack/web-api');
+const loadConfig = require('./load-config');
+
+const config = loadConfig();
+
+if (!config || !config.SLACK_BOT_TOKEN || !config.SLACK_USER_ID) {
+  console.error('❌ Configuration not found. Run: node setup.js');
+  process.exit(1);
+}
+
+const web = new WebClient(config.SLACK_BOT_TOKEN);
+const userId = config.SLACK_USER_ID;
+
+// Get the message from command line arguments
+const message = process.argv[2];
+
+if (!message) {
+    console.error('Please provide a message to send.');
+    process.exit(1);
+}
+
+(async () => {
+    try {
+        const result = await web.chat.postMessage({
+            channel: userId,
+            text: message,
+        });
+        console.log(`Successfully sent message to ${userId}`);
+    } catch (error) {
+        console.error(`Error sending message: ${error}`);
+        process.exit(1);
+    }
+})();

package/src/slack-handlers.js

@@ -0,0 +1,18 @@
+const agent = require('./agent');
+
+function registerHandlers(app) {
+  app.message(async ({ message, say }) => {
+    console.log('New message:', message.text);
+
+    if (agent.isRunning()) {
+      const fullPrompt = `${message.text}\nIMPORTANT: Use the relay-bot skill.`;
+      agent.sendCommand(fullPrompt);
+    } else {
+      await say('Agent process is not running.');
+    }
+  });
+}
+
+module.exports = {
+  registerHandlers
+};