Preface¶

DeepSeek Harness (command name dsh) splits the agent runtime into composable plugins: models, tools, sessions, sandboxes, and interfaces can all be added or removed on the Cordis kernel. The official developer preview page summarizes this as Everything is a plugin. The daily entry points are usually the terminal or the web interface launched via npx @deepseek-ai/dsh web. Once a user leaves their computer, they can no longer send messages to the same agent.

The community plugin telegram provides an alternative channel: it uses long polling via the Telegram Bot API to bridge private chat messages into agent sessions within the harness. Sending a message to the bot on your mobile phone will let the corresponding agent in the active dsh process continue its workflow; the assistant’s reply will then be sent back to the same private chat in HTML-formatted chunks. It does not register tools or skills for the model to use, only handling the “chat ↔ session” layer.

A preliminary note: the directory pages referenced below are from the independent community site DeepSeek Harness Plugin Library. The About page clearly states that this site has no official affiliation with DeepSeek / FunPlus, and should not be treated as an official app store. The official repository is deepseek-ai/deepseek-harness. This article was cross-checked against the directory details page, GitHub README / package.json / cordis.patch.yml / src/, and official Harness documentation, with a verification date of 2026-08-18.

What is this¶

telegram is a notification and integration plugin maintained by LoserFox, with its repository at LoserFox/telegram. The directory page matches the GitHub repository description: Telegram Bot API bridge, long polling, per-chat sessions, HTML formatting.

Verified attribution details:
- npm package name: @loserfox/telegram, package.json version 0.1.0
- Plugin injection line ID: telegram (see cordis.patch.yml)
- Primary language: TypeScript
- GitHub topic: dsh-plugin
- Stars: 6 on both the directory page and GitHub API
- License: Declared as BSD-3-Clause in package.json; no separate LICENSE file exists in the repository root, so the GitHub license field is empty. Please verify this manually before installation
- Directory listing date: 2026-08-05; latest repository push: 2026-08-13 (current top commit on main branch: a0a9ca11e427b62217250e2e561f6ad3c49d13f2)

It declares inject: ['agents'], relying on the @deepseek-ai/dsh-agent being attached to the host composition. LLM adapters, session persistence, and tools like bash / file reading are not included in this package, and are instead provided by the external cordis.yml (or other layers of the current profile). The README states that the design references the Telegram platform adapter from NousResearch/hermes-agent, then adapted to fit the plain-text interface requirements of the harness.

Core Features¶

Based on the README and src/bridge.ts / src/index.ts, the capabilities can be summarized as follows:

1. Long polling for messages. The plugin uses the Bot API’s getUpdates to pull updates, with a default timeout of 30 seconds. There is no webhook mode, and no public IP or domain name is required; the host running dsh only needs outbound access to the Telegram API. A single polling loop serves all chats; empty batches will sleep for 50ms to avoid event loop busy waiting.
2. One agent session per chat. Authorized text messages will create or reuse an agent based on the chat ID (ctx.agents.create), and send the original text as a user message via followup. The session ID is in the format telegram:<chatId>; /new and /clear will create a new session and release the old agent.
3. Whitelist enabled by default. allowedUserIds defaults to an empty list, which rejects all users (fail closed). allowAllUsers defaults to false, and the README notes this is only for development use. Unauthorized users will receive Access denied..
4. Token validation on load. If token is empty, it falls back to the environment variable DSH_TELEGRAM_TOKEN; if both are missing, apply will throw an error directly, without lazy startup.
5. HTML formatting and 4096-byte chunking for replies. The assistant’s text is converted to Telegram HTML using a conservative Markdown subset (fenced code blocks, inline code, **bold**, with all other content escaped), then split according to maxMessageLength (default 4096), preferring breaks at line breaks, Chinese periods, and periods followed by spaces. If a chunk of HTML is rejected by Telegram, it will fall back to plain text for that chunk. A typing chat action will be sent when turn/start is triggered. Delivery is fire-and-forget: failures are logged and discarded, with no retry ledger.
6. Slash commands do not reach the model. /start sends a welcome message, /new and /clear start a new session, /help lists available commands. Other text starting with / is treated as an unknown command. Regular user messages are added directly to the chat’s session history.

Installation and Activation¶

The installation command provided on the community directory page, run in the DeepSeek Harness terminal:

dsh plugin add github:LoserFox/telegram

The repository README also includes instructions for attaching the plugin to a specific profile (e.g., web), as well as post-installation verification and uninstallation:

# Install to a specific profile; bundle declarations will be added to the composition layer
dsh plugin --profile web add <dir|git-url>

# Verify the injection line
dsh --profile web --dump-config | grep telegram

# Uninstall
dsh plugin --profile web remove telegram

The directory page notes: For reproducible installations, you can pin the commit hash using the format dsh plugin add github:LoserFox/telegram#commit. Taking the top commit on main as seen on 2026-08-18 as an example:

dsh plugin add github:LoserFox/telegram#a0a9ca11e427b62217250e2e561f6ad3c49d13f2

Some installation constraints:
- Composition layer changes do not participate in HMR; you need to restart the target profile’s DSH process after installing or uninstalling.
- The host must have already mounted the agents service. The peerDependencies list includes @deepseek-ai/dsh-agent ^0.1.0-rc.6, as well as composite packages such as @deepseek-ai/dsh-llm, @deepseek-ai/dsh-session, @deepseek-ai/cordis, and @deepseek-ai/schemastery.
- The directory page clearly states: the plugin runs with the permissions of the current dsh process, and may execute code during installation. Inspect the source repository and license before installing.

Configuration and Typical Usage¶

Configuration Options¶

TelegramConfig in src/index.ts matches the README table:

Logs are output via ctx.logger, and the bot token will be masked. Production environments use the global fetch and real timers; client and sleep are only for testing interfaces.

Built-in telegram-agent Example from the Repository¶

The examples/telegram-agent/ directory in the repository contains a runnable cordis.yml: it includes the Telegram bridge, DeepSeek adapter, bash / file tools, subagent, todo, JSONL session persistence, and automatic compression. It references the built artifact from this repository at ../../lib/index.js, and requires a local DeepSeek Harness checkout that can resolve @deepseek-ai/* packages, with dsh available in the PATH.

Environment variables for runtime (extracted from the Chinese README of this example):

Example startup command:

cd examples/telegram-agent
DSH_TELEGRAM_TOKEN=<token> DSH_TELEGRAM_ALLOW_ALL_USERS=true \
  DEEPSEEK_API_KEY=<key> dsh --config cordis.yml

allowAllUsers=true is only suitable for local testing. For public deployments, you should use explicit DSH_TELEGRAM_ALLOWED_USER_IDS instead of enabling full public access. Tokens and whitelists should be read from environment variables, not hardcoded in cordis.yml.

How to Chat in Telegram¶

First, create a bot via @BotFather and obtain its token, then configure the token and your own user ID for the plugin. After the process starts, you can use these commands in private chats:
- /start: Establish a session, reply with the welcome message Hello! I am the DeepSeek Harness agent. Send me a message or /help for commands.
- /help: List /start, /new, /clear, /help
- /new or /clear: Start a new session, release the old agent, reply with Started a fresh session.
- Regular text: Enter the agent for that chat, and the assistant’s final text will be sent back in chunks

Polling frames and delivery calls are not visible to the model; commands will not be added to the context. Intermediate tool progress will not be streamed as separate Telegram messages: users will only see a set of chunks corresponding to each assistant output.

Applicable Scenarios and Notes¶

This is suitable for users already running DeepSeek Harness who want to use Telegram private chats as a presentation layer: follow up on the current agent while traveling, send a message to the bot to let it modify files or run commands in the local workspace. The set of tools visible to the model depends entirely on the external composition layer – the example includes bash, read / write / edit, subagent, and todo_write; if you only add this plugin to the web profile without corresponding tooling, the chat will only have a session without those tools.

The known limitations listed in the README should be understood literally before use:
- Text-only. Photos, documents, voice messages, stickers, and captions will be ignored.
- Private chats only. Group mentions and topics are not supported.
- No webhook. The process must have outbound access to the Telegram API; this package does not include proxy configuration for users in regions with restricted access.
- No delivery retries. Except for falling back to plain text when HTML is rejected, sending failures are logged and discarded.
- No hot reload for composition layers. You need to restart the dsh process after modifying the plugin.

One final security note: the plugin runs with the permissions of the current dsh process, and the bash and file tools in the example act on DSH_CWD (defaulting to the current working directory). A bot token is equivalent to login credentials, so never commit it to version-controlled configuration files. An empty whitelist rejects all users intentionally as a fail-safe measure: do not enable allowAllUsers in production just to “get it working quickly”.

Summary¶

The telegram plugin bridges Telegram private chats to agent sessions in DeepSeek Harness: it uses long polling to receive text, creates one session per chat, and sends replies back in HTML-formatted chunks. It is a community-maintained backend bridge plugin, not an official application, and does not replace the LLM, tools, or session layers. The directory page and source repository are as follows: please verify the license and current commit before installing:
- Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/telegram/
- GitHub: https://github.com/LoserFox/telegram
- Official Harness: https://github.com/deepseek-ai/deepseek-harness