@cmdop/bot

@cmdop/bot

Multi-channel bot framework for CMDOP — run /exec, /agent, /skills, and /files commands from Telegram, Discord, and Slack.

pnpm add @cmdop/bot

Quick start

import { IntegrationHub } from '@cmdop/bot';

const hub = await IntegrationHub.create({
  apiKey: process.env.CMDOP_API_KEY,
});

await hub.addTelegram({ token: process.env.TELEGRAM_TOKEN });
await hub.start();

That's it. Your bot now responds to /exec, /agent, /skills, /files, and /help.

Platform setup

Telegram

pnpm add grammy @grammyjs/transformer-throttler

await hub.addTelegram({ token: 'YOUR_BOT_TOKEN' });

Get a token from @BotFather.

Discord

pnpm add discord.js @discordjs/rest @discordjs/builders

await hub.addDiscord({
  token: 'YOUR_BOT_TOKEN',
  clientId: 'YOUR_APPLICATION_ID',
  guildId: 'OPTIONAL_GUILD_ID', // omit for global slash commands
});

Get tokens from the Discord Developer Portal.

Slack

pnpm add @slack/bolt @slack/web-api

await hub.addSlack({
  token: 'xoxb-YOUR-BOT-TOKEN',
  appToken: 'xapp-YOUR-APP-TOKEN',
});

Requires Socket Mode enabled in your Slack app settings. See examples/slack.ts for full setup.

Commands

Command	Usage	Required permission
/exec	/exec <shell command>	EXECUTE
/agent	/agent <prompt>	EXECUTE
/skills	/skills list | show <name> | run <name> <prompt>	EXECUTE
/files	/files [read] <path>	READ
/help	/help	none

Commands use a / or ! prefix. Example: /exec ls -la, !agent list running processes.

Permissions

Users default to NONE (no access). Grant levels programmatically:

const hub = await IntegrationHub.create({
  adminUsers: ['telegram:123456789'], // always ADMIN
});

// Grant a specific user READ access
await hub.permissions.setLevel('telegram:987654321', 'READ');

Permission levels (ordered, each includes all levels below):

Level	Access
NONE	No commands (only /help)
READ	/files
EXECUTE	/exec, /agent, /skills
FILES	(reserved for future write operations)
ADMIN	All commands

Cross-channel identity

Link a Telegram user to their Discord account so permissions apply on both platforms:

hub.linkIdentities('telegram', '12345', 'discord', '67890');

// Now granting EXECUTE to either ID applies to both
await hub.permissions.setLevel('telegram:12345', 'EXECUTE');

Hub options

const hub = await IntegrationHub.create({
  // CMDOP connection
  apiKey: 'cmdop_live_xxx',    // cloud; omit for local IPC
  defaultMachine: 'my-server', // pre-select a machine

  // Permissions
  adminUsers: ['telegram:123'],
  permissionStore: myRedisStore, // custom store (see PermissionStoreProtocol)

  // Startup behaviour
  channelStartMode: 'isolated', // 'isolated' (default) | 'strict'
  // 'isolated' — a failing channel is logged; others continue
  // 'strict'   — any channel failure throws and aborts hub.start()

  // Logging
  logger: myLogger, // any { info, warn, error, debug } object
});

Custom handlers

Register a handler for a new command:

import { BaseHandler, ok, err, CommandArgsError } from '@cmdop/bot';
import type { CommandContext, HandlerResult, LoggerProtocol } from '@cmdop/bot';
import type { CMDOPClient } from '@cmdop/node';

class PingHandler extends BaseHandler {
  readonly name = 'ping';
  readonly description = 'Check if the bot is alive';
  readonly usage = '/ping';
  readonly requiredPermission = 'NONE' as const;

  async handle(_ctx: CommandContext): Promise<HandlerResult> {
    return ok({ type: 'text', text: 'pong 🏓' });
  }
}

hub.registerHandler(new PingHandler(hub.cmdop, logger));

Custom channels

Implement ChannelProtocol (or extend BaseChannel) to add any messaging platform:

import { BaseChannel } from '@cmdop/bot';

class MyChannel extends BaseChannel {
  constructor(permissions, dispatcher, logger) {
    super('my-channel', 'My Platform', permissions, dispatcher, logger);
  }

  async start() {
    // connect to platform, register event listeners
    myPlatform.on('message', async (msg) => {
      await this.processMessage({
        id: msg.id,
        userId: msg.authorId,
        channelId: this.id,
        text: msg.text,
        timestamp: new Date(),
        attachments: [],
      });
    });
  }

  async stop() { await myPlatform.disconnect(); }

  async send(userId: string, message: OutgoingMessage) {
    // format and send message to platform
  }

  onMessage(handler) { /* store handler for hub use */ }
}

hub.registerChannel(new MyChannel(hub.permissions, /* dispatcher */, logger));

See examples/custom-channel.ts for a complete working example.

Multi-channel hub

const hub = await IntegrationHub.create({ apiKey: '...', channelStartMode: 'isolated' });

await hub.addTelegram({ token: process.env.TELEGRAM_TOKEN });
await hub.addDiscord({ token: process.env.DISCORD_TOKEN, clientId: process.env.DISCORD_CLIENT_ID });
await hub.addSlack({ token: process.env.SLACK_BOT_TOKEN, appToken: process.env.SLACK_APP_TOKEN });

await hub.start();

console.log(`Running: ${hub.runningChannelIds.join(', ')}`);
console.log(`Failed:  ${hub.failedChannelIds.join(', ')}`);

Graceful shutdown

async function shutdown() {
  await hub.stop(); // stops all channels, closes CMDOP client
  process.exit(0);
}

process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);

Error handling

All errors extend BotError and expose a code string:

Class	Code	When
PermissionDeniedError	PERMISSION_DENIED	User lacks required level
CommandNotFoundError	COMMAND_NOT_FOUND	Unknown command
CommandArgsError	COMMAND_ARGS	Invalid arguments
CMDOPError	CMDOP_ERROR	CMDOP client failure
MachineNotFoundError	MACHINE_NOT_FOUND	Machine hostname unknown
MachineOfflineError	MACHINE_OFFLINE	No active session on machine
ConfigError	CONFIG_ERROR	Missing / invalid configuration

Environment variables

Variable	Description
CMDOP_API_KEY	CMDOP cloud API key (omit for local IPC)
CMDOP_MACHINE	Default machine hostname
BOT_LOG_LEVEL	debug | info | warn | error (default: info)
BOT_MAX_OUTPUT	Max characters returned by /exec (default: 4000)
TELEGRAM_TOKEN	Telegram bot token
DISCORD_TOKEN	Discord bot token
DISCORD_CLIENT_ID	Discord application ID
SLACK_BOT_TOKEN	Slack bot OAuth token (xoxb-...)
SLACK_APP_TOKEN	Slack app-level token for Socket Mode (xapp-...)

Requirements

• Node.js ≥ 20
• @cmdop/node (peer dependency, installed automatically)
• Platform libraries are optional peer dependencies — install only what you use

Links

• Homepage
• Documentation
• npm

License

MIT