telegram-bot-router
Health Uyari
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 7 GitHub stars
Code Basarisiz
- process.env — Environment variable access in src/claude-binary-path.ts
- process.env — Environment variable access in src/claude-model-list.ts
- spawnSync — Synchronous process spawning in src/claude-process-kill.ts
- process.env — Environment variable access in src/claude-runner.ts
- exec() — Shell command execution in src/command-parse.ts
- process.env — Environment variable access in src/config.ts
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Control Claude Code from Telegram: one bot, one group, each topic drives Claude Code in its own project folder. Photos & files both ways.
Claude Telegram Router
English · Tiếng Việt
Control Claude Code from your phone. One Telegram bot, one group with Topics: each topic is one project. Write in a topic and Claude Code works in that project's folder on your machine, then answers in the same topic. No @bot mentions, no terminal per project.
The bot's own messages (status, commands, warnings) are in Vietnamese. Claude itself answers in whatever language you write in.
Features
- 🗂️ One topic = one project folder, each with its own Claude session and memory of the conversation.
- ⚡ Warm Claude process per topic: the first message starts it, the next ones go straight in.
- 📨 Message while Claude works: extra messages are fed into the running task, no waiting.
- 🖼️ Photos and files both ways: send screenshots, albums or documents to Claude; ask Claude to send images or files back.
- 🔔 Claude keeps going on its own when a background job (tests, build, agent) finishes.
- ⏳ Live progress: one message is edited to show Claude's latest steps.
- 🧠 Session-size warnings (tokens and message count), with a one-tap
/new. - 🎛️ Per-topic model with
/modelbuttons. - 🧩 Per-project skills with
/skillsbuttons: pick Ponytail or ClaudeKit skills to copy into the project. - 🚦 Parallel limit across topics, run timeout, stale-message skip, single-instance lock.
- 🔒 Locked to your user ID and your group; secret files (
.env, SSH keys,.pem) are never uploaded.
Requirements
- Bun ≥ 1.3
- Claude Code installed and logged in (
clauderuns in a terminal) - A Telegram account and a new bot from @BotFather
- Windows 10/11 (used daily and tested). macOS / Linux: the code handles them but they are untested; start with
bun run start.
Quick start
- Create a bot with @BotFather (
/newbot). Use a dedicated bot: only one program can receive a bot's updates (error 409). - Disable privacy mode so the bot reads every message in the group: @BotFather →
/setprivacy→ your bot → Disable (or make the bot a group admin). - Create a group → Edit → turn on Topics → create one topic per project. Add the bot after step 2 (if it was already in the group, remove and re-add it).
- Install and configure:
Fill ingit clone https://github.com/nguyencaotai1969/telegram-bot-router.git cd telegram-bot-router bun install cp .env.example .envTELEGRAM_BOT_TOKENandALLOWED_USER_IDS(your Telegram user ID). LeaveALLOWED_CHAT_IDSempty for now. - Run
start-router.cmd(Windows) orbun run start. Send any message in the group: the bot replies with the group ID (-100…). Put it inALLOWED_CHAT_IDSand restart. - Bind each topic to a folder, once:
/bind D:\projects\my-app.
Usage
After binding, write in the topic as you would to a developer sitting in that folder:
You: Run the tests and fix the failing ones
Bot: ⏳ working… (latest steps: Read, Bash, Edit…)
Bot: Fixed 2 tests in tests/api.test.ts …
✅ Done · 🧠 64k
| You want to | Do this |
|---|---|
| Give a task | Just write it: "add a logout button to the header" |
| Add details mid-task | Write again, no need to wait. The bot says "📨 sent into the running task"; Claude reads it at its next step |
| Show a bug or a design | Send a photo (or album, or file) with a caption: "the layout breaks like this, fix it" |
| Get an image or file back | "take a screenshot of the home page and send it to me", "send me the report you made" |
| Change model | /model and tap a button, or /model opus |
| Add skills to the project | /skills, pick a source, tap a skill (tap again to remove) |
| Start a new topic of conversation | /new (long sessions get slower and costlier; the bot reminds you) |
| Stop now | /stop |
| See what is going on | /status |
| Work on several projects | One topic per project; up to MAX_PARALLEL_RUNS run at once |
| Manage or move servers (no project) | Bind an empty folder, type /server and tap a button, see the example below |
Example: a server topic to move server A to server B
Every step happens in Telegram:
Create a
servertopic and bind any empty folder:/bind D:\servers.Type
/serverand tap ⚙️ Server A. The bot asks one thing at a time, you answer each with a message:Bot: Step 1/4: send the host (IP or domain) You: 1.2.3.4 Bot: Step 2/4: send the SSH port (usually 22) You: 22 Bot: Step 3/4: send the login name You: root Bot: Step 4/4: send the password You: ******** Bot: ✅ Saved server A: [email protected]:22Do the same with ⚙️ Server B. The answers never go to Claude; any command cancels. The bot speaks Vietnamese. For speed, one line works too:
/server a [email protected]:22 password.The bot deletes the message holding the password right away (it must be an admin allowed to delete messages; if it cannot, it asks you to), then saves the account to
.env.serversin the folder. The bot never sends that file to Telegram. The first time, it also copies the two files oftemplates/server-topic(written in Vietnamese) into the folder, never overwriting one that is there:ssh-to.sh: Claude runs./ssh-to.sh a 'command'to reach a server. The password reaches ssh throughSSH_ASKPASS, never the command line (which shows in the progress message on Telegram).CLAUDE.md: how to connect, the rules (A is read-only; ask before anything hard to undo on B; keepnhat-ky.md), the migration checklist. Edit it if your job differs.
Type
/serverto check (passwords are masked), then write: "inventory server A and plan the move to B".
Needs OpenSSH 8.4 or newer (Git for Windows ships one). Host keys are accepted on first connection.
How Claude sends files
Claude is told to write a line 📎 <path> (optionally 📎 <path> | caption). The router strips that line and uploads the file to the same topic: images (png, jpg, webp up to 10 MB) as photos, anything else as a document (up to 50 MB). A 📎 line inside a ``` code block is treated as an example and not sent.
Photos and files you send are saved in data/inbox/ (deleted after 7 days) and their paths are given to Claude to read.
Commands
| Command | What it does |
|---|---|
/bind <folder> |
Bind the topic to a project folder (forgets the topic's old session) |
/status |
Project, session, context size, whether Claude is working / warm / closed |
/new |
Next message starts a fresh conversation |
/model |
Pick the topic's model with buttons, or /model <name>. Applies to the running Claude without losing context |
/skills |
Pick skills with buttons: a source (Ponytail, ClaudeKit), then a skill to copy into the project's .claude/skills (✓ = already there; tap again to remove). Skills come from this machine: the installed ponytail plugin, and the ClaudeKit skills in ~/.claude/skills. Each copy gets a .router-skill.json listing its files; only a copy whose files are all unchanged is removed, so a skill the project wrote or edited is never overwritten or removed. ClaudeKit's shared _shared and common folders come along, since some skills import them. Secrets (.env, keys), links and caches are not copied |
/server |
Show the saved servers with ⚙️ Server A / ⚙️ Server B buttons: tap one and the bot asks step by step (host, port, login, password). Or one line: /server a|b user@host[:port] password. The account goes to the folder's .env.servers and copy the template ssh-to.sh and CLAUDE.md if missing; the message holding the password is deleted at once. Refused in a folder inside a git repo (the passwords could be committed) |
/stop |
Stop the current task and close the topic's Claude process (and everything it started) |
/topics |
Topics bound in this group |
/unbind |
Unbind the topic |
/id |
Chat / topic / user IDs |
/help |
Help |
Configuration (.env)
| Variable | Default | Meaning |
|---|---|---|
TELEGRAM_BOT_TOKEN |
required | Bot token from @BotFather |
ALLOWED_USER_IDS |
required | Comma-separated Telegram user IDs allowed to give orders |
ALLOWED_CHAT_IDS |
empty | Comma-separated group IDs the bot works in |
CLAUDE_BIN |
auto | Path to claude.exe; set only if auto-detection fails |
CLAUDE_MODEL |
Claude Code default | Default model for topics without /model |
MAX_PARALLEL_RUNS |
3 |
Topics working at the same time |
RUN_TIMEOUT_MINUTES |
60 |
A task running longer is stopped |
STALE_MESSAGE_MINUTES |
10 |
Messages older than this when the bot starts are skipped |
CONTEXT_WARN_TOKENS |
200000 |
Warn when the session context passes this (0 = off) |
SESSION_WARN_MESSAGES |
20 |
Warn when the session passes this many messages (0 = off) |
ROUTER_DATA_DIR |
./data |
Where state, inbox and lock file live |
Security
Claude runs with --dangerously-skip-permissions: it runs commands and edits files without asking. Anyone who can give it orders controls your machine. That is why:
- only user IDs in
ALLOWED_USER_IDS, and only in groups inALLOWED_CHAT_IDS, are obeyed; - router keys (bot token, IDs) are removed from the environment Claude runs in;
- files that look like secrets are never uploaded, whoever asks;
- forwarded messages are marked as someone else's words, for reference only.
Keep the bot token private, and only bind folders you are fine with Claude changing.
Good to know
- Your computer must be on and the router running. To start it at Windows login, put a shortcut to
start-router.cmdinshell:startup. - Each warm topic uses about 150–180 MB of RAM until
/stop,/new,/bind,/unbindor the router closes. A closed session resumes with its context (--resume). - One folder can be bound to only one topic, so two Claude sessions never edit the same place.
- Only one router can run at a time (
data/router.lock). - While the router runs Claude, the Claude Code Telegram plugin (if installed) is turned off for those runs so it does not steal the bot's messages.
claude.exeis looked up again on every start, so Claude Code auto-updates need no router restart.
See README.vi.md for more details (Vietnamese).
Development
bun install
bun run typecheck
bun run test
Tests use tests/fixtures/fake-claude.ts instead of the real claude.exe, so they cost no Claude usage.
License
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi