Preface

DeepSeek Harness (DSH) adopts a plugin architecture, aiming to decouple the Agent runtime environment from the interaction interface. dsh-telegram-bridge is a plugin running inside a DSH Profile, connecting Telegram private chats with DSH Agent sessions. With this plugin, you can directly interact with the DSH Agent via messages in Telegram, manage sessions, control model parameters, and view runtime status, without switching to the CLI or Web UI.

Core Features

The plugin provides a complete capability pipeline from interaction through presentation to stability:

  • Interaction and message management: Supports private chat bridging, a real-time status line (showing current activity or rotating neutral text to avoid making long tasks appear frozen), message queueing and interruption, independent failure retries, and regeneration.
  • Sessions and settings: Supports lightweight multi-session management, retaining the most recent N sessions and supporting one-click switching; supports dynamic switching of model, reasoning effort, and Agent preset; provides a dsh Web UI settings panel.
  • Reply presentation: Supports structured rendering (such as tables, lists, Callouts, etc.), rich text support, and intelligent splitting of long messages.
  • Stability safeguards: Includes queue persistence (restoration after restart), file logging and rotation, state backup and rollback, startup self-checks, health checks, and Telegram 429 rate-limit protection.

Installation and Enablement

Install the plugin into the web profile using the official CLI:

dsh plugin --profile web add github:JxaMe/dsh-telegram-bridge

After installation, verify that the plugin has been registered successfully:

dsh --profile web --dump-config | grep dsh-telegram-bridge

Then, you need to restart the dsh web process to load the plugin.

Configuration

The configuration file is located at ~/.dsh/dsh-telegram-bridge/config.json, and a sample configuration is generated automatically on first startup.

{
  "botToken": "123456:ABC-YOUR-REAL-BOT-TOKEN",
  "ownerId": 123456789,
  "projectRoot": "/home/you",
  "proxyEnabled": false,
  "proxyUrl": "http://127.0.0.1:7890",
  "defaultProvider": "",
  "defaultModel": "",
  "defaultReasoningEffort": "",
  "defaultAgentPreset": "",
  "errorDisplayMode": "raw",
  "htmlFormatting": true,
  "typingIndicator": true,
  "statusLine": true,
  "queueLimit": 20,
  "maxSessionsPerChat": 5,
  "debugLogging": false
}

Configuration notes and security precautions:
* After modifying the configuration file, you must restart the dsh-telegram-bridge plugin for changes to take effect.
* When modifying the configuration through the Web UI settings panel, a restart is also required after saving.
* The Web settings endpoint listens only on the loopback address to prevent unauthorized access.
* The Web endpoint requires CSRF token protection; POST requests must provide the x-csrf-token request header or the csrfToken field in the request body.

Common Commands

In the Telegram chat, you can use the following commands:

  • /start - Show the main menu
  • /new - Start a new conversation
  • /interrupt - Interrupt the current task and clear the queue
  • /status - View the status of sessions, queue, model, tokens, and more
  • /health - View uptime, message/reply/error counts
  • /sessions - View and switch between recent sessions
  • /menu - Open the settings panel
  • /commands - Open the in-chat command menu
  • /help - Show command help

How It Works

The plugin runs inside a DSH profile (usually web) and directly calls DSH native services, without requiring an additional server or Webhook.

  • Telegram side: Uses the grammY library for long polling, and handles message receiving, command parsing, and rich text rendering.
  • DSH side: As an extension of dsh, the plugin uses apiProxy to handle session and model calls, uses agents to handle task cancellation, and uses the session event to listen for Agent replies and state changes.
  • Data flow: Telegram Bot API -> dsh-telegram-bridge -> DSH API/Agents/Session -> Telegram reply.

Applicable Scenarios and Notes

This plugin is suitable for users who want to use Telegram as a mobile or instant messaging entry point to control a local or remote DSH Agent. Before using it, make sure you have a Telegram Bot Token and the corresponding User ID.

Because the plugin runs with the privileges of the DSH process, it is recommended to review the source code (the project uses TypeScript strict mode) and the license (MIT) before installation.