Skip to content
OSTwin

Bot Configuration

The OSTwin bot provides a conversational interface for managing plans and interacting with agents through Discord, Telegram, or Slack.

Architecture

Section titled “Architecture”
Discord / Telegram / Slack
       │
       ▼
  Bot (TypeScript)
       ├── Connector layer     ← Platform adapters
       ├── Command router      ← Slash commands
       ├── Agent bridge        ← Proxies to dashboard API
       ├── Session manager     ← Per-user/channel state
       └── Notifications       ← War-room event push

Environment setup

Section titled “Environment setup”

Set platform tokens in ~/.ostwin/.env:

Terminal window
# Dashboard connection
DASHBOARD_URL="http://localhost:9000"
OSTWIN_API_KEY="your-api-key"


# Discord
DISCORD_TOKEN="your-discord-bot-token"
DISCORD_CLIENT_ID="your-discord-app-id"
GUILD_ID="your-server-id"


# Telegram
TELEGRAM_BOT_TOKEN="your-telegram-bot-token"


# Slack
SLACK_BOT_TOKEN="xoxb-your-slack-bot-token"
SLACK_APP_TOKEN="xapp-your-slack-app-token"
SLACK_SIGNING_SECRET="your-signing-secret"

Discord setup

Section titled “Discord setup”

  1. Create a Discord application at the Developer Portal. Under Bot, click Add Bot and copy the token.

  2. Set permissions: Send Messages, Read Message History, Use Slash Commands, Embed Links, Attach Files.

  3. Invite the bot using an OAuth2 URL with bot and applications.commands scopes.

  4. Configure tokens in ~/.ostwin/.env:

    Terminal window
    DISCORD_TOKEN="your-bot-token"
    DISCORD_CLIENT_ID="your-application-id"
    GUILD_ID="your-server-id"

  5. Deploy slash commands and start:

    Terminal window
    cd bot && npm install
    npx ts-node src/deploy-commands.ts
    npm start

Telegram setup

Section titled “Telegram setup”

  1. Create a bot via @BotFather in Telegram. Send /newbot and copy the token.

  2. Configure the token:

    Terminal window
    TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."

  3. Start the bot. The Telegram connector activates automatically when the token is present.

    Terminal window
    cd bot && npm start

Commands

Section titled “Commands”
Command Description
/plan create Interactive plan creation
/plan run <path> Execute a plan
/plan status Current execution status
/plan list List available plans

Agent bridge

Section titled “Agent bridge”

The agent bridge proxies conversations between chat users and OSTwin agents:

  1. Routes user messages to the appropriate war-room channel
  2. Waits for the agent’s response
  3. Formats and returns the response to the chat platform

Sessions

Section titled “Sessions”

Per-user context: current plan, active war-room, conversation history (last 20 messages), notification preferences. Expires after 24 hours of inactivity.

Notifications

Section titled “Notifications”

The bot pushes war-room events to subscribed channels:

Event Notification
Room enters review “Room-001 is ready for review”
Room passed “Room-001 passed QA”
Room failed-final “Room-001 failed after max retries”
Plan completed “Plan completed — 4/4 epics passed”

Subscribe with /subscribe room-001 or /subscribe plan my-plan.

Connector architecture

Section titled “Connector architecture”
bot/src/connectors/
├── base.ts        # Abstract interface
├── discord.ts     # Discord adapter
├── telegram.ts    # Telegram adapter
├── slack.ts       # Slack adapter
└── registry.ts    # Auto-activates based on tokens

The registry activates connectors based on which tokens are set. Discord and Telegram can run simultaneously from a single process.