Connecting Telegram to Claude Code

This guide is written for someone who has never opened Terminal before. Take it one step at a time. You cannot break anything by following these steps carefully.

What This Does

This lets you chat with Claude Code from the Telegram app on your phone. You message your Telegram bot, and your messages get routed to a Claude Code session running on your Mac. Claude's replies come back to you in Telegram. You can even approve Claude's permission requests from your phone.

Think of the bot as a walkie-talkie between your phone and the Claude session on your computer.

The Pieces That Have To Be In Place

Once the tools are installed, all of these need to be true for the bot to respond. If messaging the bot does nothing, one of these is missing. This guide sets up each one.

How To Open Terminal

Most of the Mac steps use Terminal, a built-in app where you type commands instead of clicking buttons.

1. Hold down the Command key and tap the Spacebar. A search box appears in the middle of your screen.
2. Type Terminal.
3. Press Return. A window with text and a blinking cursor opens.

That is Terminal. To run a command, click inside the window, paste the command with Command + V, and press Return.

Step 1: Install Homebrew

Homebrew is the app store for Terminal. It is what we use to install other tools. In Terminal, paste this and press Return:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

It will explain what it is about to do and ask you to press Return to continue, then ask for your Mac password. This takes a few minutes.

Important: finish the install. When it is done, Homebrew prints a "Next steps" message asking you to run two more commands so Terminal can find it. On a modern Mac with Apple Silicon, those are:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

Paste each one and press Return.

To confirm Homebrew works, run:

brew --version

You should see a version number. If you ever see command not found: brew later, it is because these two "Next steps" commands were skipped.

Step 2: Install Claude Code

Now install Claude Code itself. In Terminal, paste this and press Return:

curl -fsSL https://claude.ai/install.sh | bash

When it finishes, close Terminal and open a fresh Terminal window so it picks up the new command, then check it:

claude --version

You should see a version number. The first time you run claude, it will ask you to log in. Follow the on-screen prompt to sign in with your Anthropic or Claude account.

Step 3: Install bun

bun is the program that runs the Telegram bridge. Now that Homebrew is installed, this is one line:

brew install bun

Wait until your cursor returns to a fresh line, then confirm it:

bun --version

You should see a version number like 1.3.14.

Step 4: Open Claude Code And Install The Telegram Plugin

The /telegram:* commands do not exist until you install the Telegram plugin. Open a fresh Terminal window and launch Claude Code:

claude --dangerously-skip-permissions

The first time it runs, it asks you to log in. Follow the prompt to sign in with your Anthropic or Claude account.

Once Claude Code is open, type these two commands one at a time, pressing Return after each. Type them into the Claude Code prompt, not Terminal.

Add the official plugin marketplace:

/plugin marketplace add anthropics/claude-plugins-official

Install the Telegram plugin from it:

/plugin install telegram@claude-plugins-official

After it installs, you will see telegram listed as enabled. The /telegram:... commands are now available.

Step 5: Create Your Telegram Bot

Your phone talks to a Telegram bot that you create for free using Telegram's official bot-maker, BotFather. This step happens entirely in the Telegram app.

1. Open Telegram on your phone or computer.
2. In the search bar, type BotFather and open the official one. It has a blue checkmark next to the name @BotFather.
3. Tap Start, then send /newbot.
4. BotFather asks for a name. This is the display name, and can be anything, for example My Claude Bot.
5. Then it asks for a username. This must be unique and end in bot, for example myclaude_bot. This username is what you will message, so pick something you will remember.
6. BotFather replies with a token that looks like 8748724468:AAGPNp0QhCsfIaDxG8.... Copy it and keep it private. Anyone with this token can control your bot.

Step 6: Save The Bot Token In Claude Code

With Claude Code still open from Step 4, paste your token into this command. Replace the placeholder with the real token from BotFather:

/telegram:configure PASTE-YOUR-TOKEN-HERE

That connects Claude Code to your bot. If you ever need to check or change it, run /telegram:configure on its own.

Step 7: Turn On Channels

This is the step most likely to be missed, because the setting is off by default and lives in a protected system folder. This must be done in the real Terminal app. It will not work if you try to run it from inside Claude Code, because Claude cannot type your password for you.

Open Terminal, then paste these two commands, pressing Return after each one.

Command 1 creates the folder and will ask for your password:

sudo mkdir -p "/Library/Application Support/ClaudeCode"

Command 2 writes the setting and prints it back:

echo '{ "channelsEnabled": true }' | sudo tee "/Library/Application Support/ClaudeCode/managed-settings.json"

After Command 2, Terminal should print:

{ "channelsEnabled": true }

Seeing that line means it worked.

Step 8: Launch Claude Code With The Telegram Bridge On

Settings and channels are only read when Claude Code starts, so launch it fresh. Claude Code is almost certainly still open from Steps 4-6. Fully quit it first by typing /exit and pressing Return.

In Terminal, paste this and press Return:

caffeinate -dimsu claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions

What each part does:

• caffeinate -dimsu keeps your Mac awake. If the computer goes to sleep, the Claude session pauses and the bot stops responding to your phone. It lets the Mac sleep normally again when you quit Claude.
• --channels plugin:telegram@claude-plugins-official turns on the Telegram bridge. Without this, none of the Telegram features work.
• --dangerously-skip-permissions lets Claude run actions without stopping to ask permission each time. It is convenient, especially when you are driving Claude from your phone and cannot click Allow on the Mac, but Claude will not pause before running commands or editing files. Only use it on a machine and project you trust.

Step 9: Pair Your Phone

Pairing tells the bot that your Telegram account is allowed to reach Claude.

1. Open Telegram on your phone.
2. Search for your bot, @demowhaibot in this guide, and open the chat.
3. Tap Start, or send any message like hi.
4. The bot replies with a 6-character code, for example 5f51ef.
5. Back in Claude Code on your Mac, type this using your code:

/telegram:access pair 5f51ef

The bot sends you Paired! Say hi to Claude. in Telegram. If you have already paired before, you can skip this. You stay paired.

Step 10: Use It

Now just message your bot from Telegram. Your message reaches the Claude session on your Mac, and Claude's reply comes back in Telegram. Done.

Recommended: Lock It Down

While pairing is on, anyone who finds your bot can request a code. Once you are paired and nobody else needs access, lock it to an approved-only list. In Claude Code type:

/telegram:access policy allowlist

This stops the bot from handing out new pairing codes. You stay connected.

Troubleshooting: I Message The Bot And Nothing Happens

Work through these in order. Most problems are one of the pieces above being missing.

1. Is The Bridge Program Running?

In Terminal, paste:

ps aux | grep "bun server.ts" | grep -v grep

If you see a line mentioning bun server.ts, it is running. If you see nothing, the bridge is not running. Re-check Steps 3, 7, and 8.

2. Is The Telegram Plugin Installed?

In Claude Code, type /telegram:configure. If it says the command is unknown, the plugin is not installed. Redo Step 4.

3. Is bun Installed And Findable?

bun --version

A version number means good. command not found means redo Step 3.

4. Is The Channels Setting In Place?

cat "/Library/Application Support/ClaudeCode/managed-settings.json"

You want to see { "channelsEnabled": true }. If it says "No such file", redo Step 7.

5. Did You Restart Claude Code?

Reloading plugins is not enough for the token and channel settings to take effect. Fully quit with /exit and relaunch with the full command from Step 8.

6. Are You Messaging The Exact Right Bot?

It must be your bot's username. The example in this guide is @demowhaibot. A similarly named bot will not work.

7. Did It Work, Then Go Quiet After A While?

Your Mac probably went to sleep, which pauses the Claude session. Relaunch using the caffeinate command from Step 8, and for an unattended laptop keep it plugged into power.

brew: command not found

Either Homebrew is not installed, or the two "Next steps" commands at the end of Step 1 were skipped. Run them now, then continue.

Last updated 2026-06-18.