Claude Code in your pocket

The Claude Code Telegram Bridge lets you send a message from Telegram and run a Claude Code turn on your own machine. It is a Python bridge around the installed CLI, not a separate model or a terminal emulator.

Claude also has its own Remote Control for browser and mobile access. This project is for people who want that conversation in Telegram.

What a message does

Ordinary text is queued for claude -p. The bridge reads Claude’s structured output and sends text replies back to the chat. Later turns use --resume when a stored session is available.

That provides conversation continuity, not an identical copy of the terminal interface. Tools, project instructions and skills depend on the installed Claude Code version and its configuration. The bridge passes unhandled slash commands through as prompt text; it does not implement every interactive CLI command.

Photos, voice and files

• Uploads: photos, documents, audio and video are downloaded to the server. Their paths are included in the prompt. The bridge does not itself understand an image or decode a video; what Claude can inspect depends on the model and available tools.
• Albums: the code groups related uploads before queuing a prompt. Downloads and transcription run outside the polling thread.
• Voice: optional transcription tries ElevenLabs first, then Gemini when configured and within the fallback’s size guard. It requires your own provider keys. If transcription fails or is unavailable, the audio path is passed to Claude instead.
• Files out: /file /absolute/path sends an existing file the bridge process can read. The code refuses files larger than 49 MiB. It sends file contents unchanged, so check them for secrets first.

The Claude child process also receives the bot token and destination chat ID so it can send artifacts directly. That is useful, but it is also access you are deliberately granting.

Sessions and commands

Session browsing is scoped to the configured CLAUDE_WORKDIR under the service user’s Claude projects directory. It does not list every conversation from every project or user on the server.

Command	What it does
/new	Clears this chat’s selected session; the next turn starts fresh
/sessions	Lists up to ten recent sessions for the configured working directory
/attach <prefix>	Selects a session when its ID prefix matches uniquely
/last	Selects the newest listed session other than the current one
/file <path>	Sends a readable file within the bridge’s size guard
/stop	Kills the running Claude process group and drops queued prompts
/status, /log	Shows bridge state or recent log text
/reboot	Exits the bridge so systemd can restart it

If a saved session file is missing, the bridge starts fresh. Certain failed resume attempts are retried once without the old session. Starting fresh does not preserve the missing conversation.

Setting it up

The repository includes bridge.py, .env.example, a dashboard and a sample systemd service. The bridge uses Python’s standard library; Claude Code is a separate installation with its own login and usage requirements.

1. Use a Linux machine with systemd and Python 3.10 or newer. Install Claude Code and confirm it works as the account that will run the service.
2. Clone the repository. Copy .env.example to .env, set TG_TOKEN and your numeric OWNER_ID, and restrict the file’s permissions with chmod 600 .env.
3. Set CLAUDE_BIN and CLAUDE_WORKDIR explicitly for that account. Make sure it can write the bridge’s state, log and upload directories.
4. Adapt the sample service before enabling it. Its paths assume /opt/claude-tg-bridge, and it has no User= line, so a system service installed unchanged runs as root. Set a dedicated User= and the appropriate environment and paths rather than assuming it runs as your shell user.
5. Enable the adapted service, then open your bot in a private Telegram chat and test a small request.

Do not reuse a token that another bot gateway or poller is already consuming.

The security boundaries

Incoming messages are checked against OWNER_ID. Non-owner private messages get a throttled refusal; non-owner group messages are ignored. This is a sender check, not a sandbox. Use a private chat and protect both your Telegram account and bot token.

Claude runs with --dangerously-skip-permissions. The bridge explicitly supplies that flag. Its access is therefore bounded by the service account’s operating-system permissions, not interactive tool approvals. A compromised owner account can become access to that account’s files and commands.

Token redaction is limited. The bridge replaces the literal token in text sent through its text helper and in the dashboard’s log excerpt. It does not scrub arbitrary files, direct Bot API calls made by Claude, or every field the dashboard can display. “The token never leaks” would be an unjustified promise.

The poller lock is local. It prevents another copy using the same installation’s lock file. It cannot stop a different directory, server or application from polling the same bot token.

Queued work is not durable. The update offset is saved after the handler dispatches work, not after Claude finishes it. Prompts and pending media live in memory, so a restart can lose accepted work. This is not an exactly-once job queue.

The optional dashboard

The dashboard is disabled unless both DASH_PORT and DASH_KEY are set. It exposes status, queue size, recent sessions and runs, upload metadata, logs and system information. Its CPU display is based on load average, not a direct CPU-utilisation measurement. An optional Solana panel reads wallet information.

The HTTP routes are read-only and the key comparison uses hmac.compare_digest. However, the server binds to all interfaces and does not provide TLS itself. Keep it behind a firewall, private tunnel or authenticated HTTPS proxy. A key in a URL can also end up in browser history or proxy logs.

The bridge is small enough to inspect before installing. Read the source and setup notes, choose the service account carefully, and treat it as remote access to a real machine.