dsh-tg-bridge

dsh-tg-bridge

Drive DeepSeek Harness from Telegram. It runs on the

machine that already has the harness, and it answers in the chat where you asked.

A forum topic is a project: its own session, working directory, model,

permissions and language. Two topics share the install and nothing else.

Never made a bot? [QUICKSTART.md](QUICKSTART.md) goes from "no account" to a bot

that answers, one step at a time.

What it does

• A model per topic. /model lists the routes the profile declares — provider

and model together — and a tap switches this topic only. /model <route> all

moves the default the other topics follow; /model auto hands the topic back.

A chat for thinking out loud and a chat for engineering no longer share one model.

• A topic is a project. /cd my-app, and every turn runs from that directory —

on a permission-enabled profile the sandbox is narrowed to it too, so the agent

cannot write outside the project.

• One edited message per turn. Steps, a timer and the cache hit rate, plus the

reasoning in a collapsed block you can tap open. A long turn adds a second

collapsed block with every tool call. /stop is a button on that message.

• /diff — review the turn, one hunk at a time. The working tree is split into

files and hunks; every hunk gets two buttons: explain it, or revert just that

hunk. A button carries a hash of the hunk it was drawn from, so a press that

arrives after the file moved on is refused instead of touching a line nobody was

looking at. /diff stat is the file list alone.

• An endpoint from the chat. `/endpoint add <id> <https://url/v1> <KEY_ENV>

[model,model]` writes the provider without an AI turn, and the key itself is

never typed — only the name of the variable that holds it. The new models appear

on /model as routes.

• Input: text, voice, photos. Any speech engine plugs in — a local script, any

command-line tool, or an OpenAI-compatible API (see [docs/VOICE.md](docs/VOICE.md))

— and the transcript is shown before the answer. A photo is read by the turn's own

model through read_image, text and UI included; no second model is needed.

• Goal and checklist per topic. /goal, /tasks; both survive restarts and

are prepended to every turn.

• Two scopes for every setting. /reasoning <mode> all moves the default,

without all it moves this topic; language and pinning follow the same rule,

and /crew use reviewer gives one topic its own effort, permissions and agent

preset (four built-in sets, read-only, copyable).

• It says what it cost. A turn reports tokens and the cache hit rate; /cost

says what the session has spent and /prices shows the rates it used.

• Out of quota is not a dead end. When the quota runs out it switches to a

free model right away, and the answer says which route answered.

• No lost messages. A journal with acknowledgement and replay.
• Knows how busy the computer is. /load shows free space on the topic's disk,

free RAM and average CPU, plus how many turns are running and waiting. /load on

makes a prompt wait instead of starting while the machine is over a limit you set

— kept, never refused, and one press sends it anyway.

• Languages. Menus and service messages in en, ru, zh; /lang pins the

topic language, and without it a new topic takes the language of the message

itself (Cyrillic → ru, Han characters → zh), then the Telegram

language_code, then en.

• "Stop" / "Retry" buttons and tool confirmations sit in the message, so there

is no command to type to stop a run.

• /report. One command turns "it broke" into a redacted document: version,

profile, preset, model, directory, the last failure and the log tail, with keys

and home paths removed before the file is written.

• dsh-tg check. Diagnostics in one command, changing nothing on the system.

First run

setup.mjs leaves a working bridge with these defaults, and none of them need

a decision before the first message:

Setting · Default · Where to change it

profile · headless · /profile

folder · the workspace you ran setup in · /cd

idle limit · 2 minutes without output stops the turn · /settings

hard ceiling · none — a long turn runs until it ends · /settings

parallel turns · 3 · /settings

plain text · off (Markdown answers) · /settings

model fallback · on, empty chain · /fallback

voice messages · off · /voice

topic log · on · /settings

command menu · installed for this bot · node bot-menu.mjs

The first three commands are enough to be productive: /cd <project> binds the

topic to a folder, /model picks the model with buttons, /menu is every

command as a card, grouped. /start answers with the same three and offers a five-step tour — folder, model, files, the turn and the way back, the switches — each step naming one command as a button; /help

explains any command in one message; /settings holds the switches above.

Requirements

• Node.js ≥ 24 (the version DeepSeek Harness ships; sessions are zstd-compressed)
• DeepSeek Harness 0.2.1-rc.2 or newer in the 0.2.x line (>=0.2.1-rc.2 <0.3.0)
• DeepSeek Harness installed (~/.dsh/profiles/headless)
• A Telegram bot token from @BotFather

The supported harness range is declared in engines.dsh; that field decides

compatibility on its own (DSH ignores peerDependencies when it is present).

The range includes an explicit prerelease branch, because a plain <0.3.0

silently excludes 0.2.2-* builds. A future 0.3.0 needs an explicit bump:

the bridge relies on the 0.2.x CLI flags and profile layout.

Ecosystem

The Chinese DSH community maintains the largest plugin catalogs and the

in-app markets that read them; this bridge follows their packaging rules so it

can be listed next to them:

• [awesome-dsh-plugin](https

…(truncated)