clanker-agent/packages/companion-channels

@e9n/companion-channels

Two-way channel extension for companion — route messages between agents and Telegram, Slack, webhooks, or custom adapters.

Features

• Telegram adapter — bidirectional via Bot API; polling, voice/audio transcription, allowedChatIds filtering
• Slack adapter — bidirectional via Socket Mode + Web API
• Webhook adapter — outgoing HTTP POST to any URL
• Chat bridge — incoming messages are routed to the agent as prompts; responses sent back automatically; persistent (RPC) or stateless mode
• Event API — channel:send, channel:receive, channel:register for inter-extension messaging
• Custom adapters — register at runtime via channel:register event

Settings

Add to ~/.companion/agent/settings.json or .companion/settings.json:

{
  "companion-channels": {
    "adapters": {
      "telegram": {
        "type": "telegram",
        "botToken": "env:TELEGRAM_BOT_TOKEN",
        "polling": true
      },
      "alerts": {
        "type": "webhook",
        "headers": { "Authorization": "env:WEBHOOK_SECRET" }
      }
    },
    "routes": {
      "ops": { "adapter": "telegram", "recipient": "-100987654321" }
    },
    "bridge": {
      "enabled": false
    }
  }
}

Use "env:VAR_NAME" to reference environment variables. Project settings override global ones.

Adapter types

Type	Direction	Key config
telegram	bidirectional	botToken, polling, parseMode, allowedChatIds, transcription
slack	bidirectional	botToken, appToken
webhook	outgoing	method, headers

Bridge settings

Key	Default	Description
enabled	false	Enable on startup (also: --chat-bridge flag or /chat-bridge on)
sessionMode	"persistent"	"persistent" = RPC subprocess with conversation memory; "stateless" = isolated per message
sessionRules	[]	Per-sender mode overrides: [{ "match": "telegram:-100*", "mode": "stateless" }]
idleTimeoutMinutes	30	Kill idle persistent sessions after N minutes
maxQueuePerSender	5	Max queued messages per sender
timeoutMs	300000	Per-prompt timeout (ms)
maxConcurrent	2	Max senders processed in parallel
typingIndicators	true	Send typing indicators while processing

Tool: notify

Action	Required params	Description
send	adapter, text	Send a message via an adapter name or route alias
list	—	Show configured adapters and routes
test	adapter	Send a test ping

Commands

Command	Description
/chat-bridge	Show bridge status (sessions, queue, active prompts)
/chat-bridge on	Start the chat bridge
/chat-bridge off	Stop the chat bridge

Install

companion install npm:@e9n/companion-channels

License

MIT