How to contribute to TRD, build from source, and debug issues.
make build # CGO_ENABLED=1 go build → bin/trd
make install # build + copy to ~/.local/bin/trd
make test # go test ./...
make lint # go vet ./...
make install-models # download whisper + TTS models (~230MB)
make restart # rebuild + restart dispatcher in tmux
make start # start dispatcher (reads saved config from DB)First-time setup:
make setup TELEGRAM_BOT_TOKEN=123456:ABCDEF...This builds, installs channel plugin deps, starts the dispatcher in a tmux session named trd, and saves config to the database.
| Package | Why | Install |
|---|---|---|
| Go 1.22+ | compiles the dispatcher | go.dev/dl |
libopus-dev |
Opus codec for voice (CGo) | apt install libopus-dev libopusfile-dev |
bun |
runs the channel plugin | curl -fsSL https://bun.sh/install | bash |
CGo is required (CGO_ENABLED=1) because of sherpa-onnx (whisper + TTS) and libopus.
cmd/trd/main.go CLI entry point, subcommand dispatch
internal/
dispatcher/dispatcher.go The hub — Telegram poll, WS, tmux, health loop
ws/ws.go WebSocket server + Frame protocol
storage/storage.go bbolt wrapper (instances, allowlist, settings)
media/media.go Whisper STT + VITS TTS (sherpa-onnx embedded)
audio/audio.go OGG/Opus decode/encode (replaces ffmpeg)
telegram/telegram.go Minimal Telegram Bot API client
tmuxmgr/tmuxmgr.go tmux session management
config/ Paths, repo config, gitignore
channel/index.ts MCP channel plugin (Bun/TypeScript)
cmd/trd → dispatcher → storage, telegram, tmuxmgr, ws, config, media
media → audio
Leaf packages (config, storage, audio, telegram, tmuxmgr) have no internal deps. Don't introduce cycles.
- Fork this repo and clone it.
- Set up TRD pointing at your fork — you can develop it through Telegram using TRD itself.
- Make changes, test with
make test, submit a PR.
TRD can manage its own repo. After the initial setup:
- Create a topic in your Telegram group.
- Send
/start git@github.com:you/multi-claude-tg.git. - Run
make self-modify NAME=multi-claude-tgto point the channel plugin at the instance's checkout. - Now edits to
channel/index.tsin the instance take effect on restart.
For Go changes, tell Claude to run make restart — it rebuilds the binary and restarts the dispatcher. Channel plugins reconnect automatically.
- Telegram client is a hand-rolled
net/httpwrapper — keep it minimal (only methods TRD actually calls). - Channel plugin stays thin (~470 lines). Business logic goes in the Go dispatcher; route via a new WS frame type.
- tmux session names are
trd-<instance-id>.tmuxmgr.SessionNameis the single source of truth. - Secrets in
.trd/config.jsonat mode 0600. Dispatcher WS on127.0.0.1only. .trd/is auto-gitignored in cloned repos. Don't remove.
- Add the case in
handleMessage's switch block indispatcher.go. - Write the
cmd<Name>handler method. - Update the README Telegram commands table.
- Add the field(s) to
ws.Frameif needed. - Handle the new
frame.Typecase indispatcher.OnOutbound. - Add the corresponding tool in
channel/index.ts(ListToolsRequestSchema + CallToolRequestSchema handlers).
Three log sources to check:
tmux attach -t trd # live logs (Ctrl+B, D to detach)
tail -f ~/.trd/trd.log # from another terminal
trd start --debug # verbose mode (or TRD_DEBUG=1)Toggle debug at runtime: send /debug in any Telegram topic. New/restarted Claude instances will include/omit --debug accordingly.
tail -f /tmp/trd-channel.logOverride path with TRD_CHANNEL_LOG env var. Shows: WS connect/disconnect, frame send/recv, MCP notification delivery, tool calls.
ls -lt ~/.claude/debug/ # most recent session first
tail -100 ~/.claude/debug/<session-id>.txtMCP protocol from Claude's side — useful when the plugin connects but messages aren't getting through.
| Symptom | Check |
|---|---|
| Message not arriving | trd.log: look for "tg recv" → "tg->claude forward" → "frame queued". If "no live channel", plugin isn't connected. |
| Plugin not connecting | /tmp/trd-channel.log: look for "ws connect" / "ws error". Verify .trd/config.json port + secret. |
| Claude not responding | /watch in the topic. Check for rate-limit prompts (watchdog auto-dismisses). |
| TTS/Whisper broken | trd.log: search for "whisper:" or "tts" entries. Verify models in ~/.trd/models/. |
| Rate-limited | Watchdog auto-dismisses and notifies topic. Check trd.log for "rate-limit detected". |
| Variable | Purpose | Persisted |
|---|---|---|
TELEGRAM_BOT_TOKEN |
Bot authentication | Yes |
TRD_PORT |
Dispatcher HTTP/WS port (default 7777) | No |
TRD_CHANNEL_ENTRY |
Path to channel plugin source | Yes |
TRD_WHISPER_MODEL_DIR |
Whisper model directory | Yes |
TRD_TTS_MODEL_DIR |
TTS model directory | Yes |
TRD_OPENAI_API_KEY |
OpenAI API fallback for STT/TTS | Yes |
TRD_ALLOWED_USERNAMES |
Comma-separated allowlist | Yes |
TRD_DEBUG |
Set to "1" for debug mode | No |
TRD_HEALTH_INTERVAL_SEC |
Health loop interval (default 30) | No |
TRD_CLAUDE_BIN |
Claude binary name (default "claude") | No |
TRD_CLAUDE_ARGS |
Override Claude arguments entirely | No |
TRD_CLAUDE_CONFIRM_KEYS |
Keys to send for dev-channels prompt (default "Enter") | No |
"Persisted" means saved to bbolt on first start and restored on future starts when the env var isn't set.
- Authorization: Supergroup membership = authorized. User allowlist (
trd allow/deny) adds fine-grained control. - Secrets: Per-instance 256-bit secret in
.trd/config.json(mode 0600). Unknown secrets rejected. - Networking: Dispatcher on
127.0.0.1only. No external exposure. - Private repos: SSH agent /
~/.ssh/config. .mcp.jsonis mode 0644 — it's just a pointer to the channel plugin, not a secret.