How to Use Telegram with Claude Code for Mobile AI Agent Access

Dispatch AI Tasks From Anywhere — Mobile Access to Claude Code via Telegram

If you run Claude Code on a development machine, you already know the bottleneck: you have to be sitting at your terminal. Want to kick off a refactor while commuting? Start a long-running research task from your phone and check back later? That’s not possible by default.

The fix is simpler than it sounds. By pairing Claude Code with Telegram using a channels bridge and a persistent tmux session, you get a mobile interface to your AI agent that works anywhere you have signal. You send a message from your phone, Claude Code receives it and starts working, and you walk away while the agent runs in the background.

This guide covers the full setup: configuring tmux for persistent sessions, creating a Telegram bot, wiring up the channels plugin, and dispatching tasks like a pro from your phone.

---

Why This Setup Is Worth Building

Claude Code is built for the terminal. That’s a strength — direct filesystem access, full shell execution, and deep integration with your dev environment. But it’s also a constraint.

Most serious uses of Claude Code involve long-running tasks: large refactors, multi-file generation, research pipelines, automated test runs. These aren’t tasks you want to babysit. You want to start them and come back when they’re done.

Telegram solves the interface problem. It’s available on every mobile platform, has a mature bot API, supports long messages, handles media, and doesn’t require a separate app. If you already use Telegram, your AI agent fits right into your existing workflow.

The tmux layer solves the session problem. When you close a terminal or disconnect from a server, processes die. Tmux keeps your Claude Code session running in a detached state so the agent can keep working even if you close your laptop, lose SSH connectivity, or put your phone in your pocket.

Together, these tools give you a reliable mobile interface to your AI agent — no cloud infrastructure required.

---

Prerequisites Before You Start

Before touching any config files, make sure you have the following in place:

Required:

• Claude Code installed and authenticated (npm install -g @anthropic-ai/claude-code)
• Tmux installed on your machine (brew install tmux on macOS, apt install tmux on Ubuntu)
• A Telegram account
• Node.js 18+ installed
• A terminal you can leave running (local machine, remote VPS, or cloud instance)

Optional but recommended:

• A dedicated server or always-on machine (a VPS works great for this — even a $5/month instance is fine)
• SSH access to that machine so you can check in from your laptop when needed

If you’re running this on a remote server, you’ll get the best experience — your agent runs 24/7 and you can trigger tasks from anywhere without worrying about your laptop sleeping.

---

Set Up Tmux for Persistent Sessions

Tmux is the foundation of this whole setup. Without it, your Claude Code process dies the moment you disconnect.

Install and Verify Tmux

On macOS:

brew install tmux

On Ubuntu/Debian:

sudo apt update && sudo apt install tmux

Verify the install:

tmux --version

Create a Named Session for Claude Code

Named sessions make it easy to reattach and reference from scripts later. Start a new session called claude-agent:

tmux new-session -d -s claude-agent

The -d flag creates it in detached mode (it runs in the background). You can attach to it anytime:

tmux attach -t claude-agent

And detach again without killing it with Ctrl+B, then D.

Verify the Session Persists

Test that the session stays alive after you close your terminal:

1. Start a session: tmux new-session -d -s test-session
2. Close your terminal window
3. Open a new terminal and run: tmux list-sessions
4. You should see test-session still listed

If that works, tmux is functioning correctly. Your Claude Code agent will now survive disconnects.

---

Create Your Telegram Bot

Telegram bots are created through a built-in bot called BotFather. The process takes about two minutes.

Register a New Bot with BotFather

1. Open Telegram and search for @BotFather
2. Start a conversation and send /newbot
3. Follow the prompts: give it a name (e.g., “My Claude Agent”) and a username (must end in bot, e.g., my_claude_agent_bot)
4. BotFather will return a token that looks like this: 7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxx

Save this token. You’ll need it in the next section.

Get Your Chat ID

The bot needs to know who to listen to. The easiest way to get your personal chat ID:

1. Send any message to your new bot
2. Open this URL in a browser, replacing YOUR_TOKEN with your bot token: https://api.telegram.org/botYOUR_TOKEN/getUpdates
3. Find the "chat" object in the JSON response — the "id" value inside it is your chat ID

Note that chat ID down too. You’ll use it to ensure the bot only responds to your messages.

---

Wire Up the Channels Bridge

This is the core integration layer. You need a process that:

1. Polls Telegram for new messages from you
2. Forwards those messages to the tmux session running Claude Code
3. Captures Claude Code’s output
4. Sends it back to you on Telegram

Install the Required Dependencies

Create a new directory for your bridge service:

mkdir ~/claude-telegram-bridge && cd ~/claude-telegram-bridge
npm init -y
npm install node-telegram-bot-api

Write the Bridge Script

Create a file called bridge.js:

const TelegramBot = require('node-telegram-bot-api');
const { exec } = require('child_process');
const { execSync } = require('child_process');

const TOKEN = process.env.TELEGRAM_BOT_TOKEN;
const ALLOWED_CHAT_ID = parseInt(process.env.TELEGRAM_CHAT_ID);
const TMUX_SESSION = process.env.TMUX_SESSION || 'claude-agent';

const bot = new TelegramBot(TOKEN, { polling: true });

bot.on('message', (msg) => {
  const chatId = msg.chat.id;

  // Only respond to your own messages
  if (chatId !== ALLOWED_CHAT_ID) {
    return;
  }

  const text = msg.text;
  if (!text) return;

  // Handle /status command to check if session is alive
  if (text === '/status') {
    try {
      const sessions = execSync('tmux list-sessions').toString();
      bot.sendMessage(chatId, `Active sessions:\n${sessions}`);
    } catch (e) {
      bot.sendMessage(chatId, 'No active tmux sessions found.');
    }
    return;
  }

  // Send the message to the Claude Code tmux session
  const escaped = text.replace(/'/g, "'\\''");
  exec(`tmux send-keys -t ${TMUX_SESSION} '${escaped}' Enter`, (err) => {
    if (err) {
      bot.sendMessage(chatId, `Error sending command: ${err.message}`);
    } else {
      bot.sendMessage(chatId, `✓ Dispatched to Claude Code session`);
    }
  });
});

console.log('Bridge running...');

Configure Environment Variables

Create a .env file (or set these in your shell profile):

export TELEGRAM_BOT_TOKEN="your_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
export TMUX_SESSION="claude-agent"

Source the file:

source .env

Start Claude Code in the Tmux Session

Now start Claude Code inside the tmux session you created earlier:

tmux send-keys -t claude-agent 'claude' Enter

Or attach to the session and start it manually:

tmux attach -t claude-agent
# then type: claude
# then detach with Ctrl+B, D

Start the Bridge

node bridge.js

You should see “Bridge running…” in the terminal. Keep this process running — or better, run it in its own tmux session:

tmux new-session -d -s bridge 'node ~/claude-telegram-bridge/bridge.js'

---

Test the Full Pipeline

With both sessions running, open Telegram and send a message to your bot:

Can you list the files in the current directory?

You should receive a confirmation that the command was dispatched. If you attach to the claude-agent tmux session, you’ll see Claude Code processing the request.

For tasks that complete quickly, you can extend the bridge to capture terminal output and send it back. For long-running tasks, the pattern works differently — you dispatch the task, detach, and check back later by attaching to the tmux session directly or adding a notification callback in your script.

---

Dispatch Patterns That Actually Work

Once the pipeline is running, here are the patterns that make it genuinely useful.

Fire-and-Forget Tasks

These are tasks you start and don’t need to watch:

• “Review all TypeScript files in /src and add JSDoc comments”
• “Run the test suite and save the output to test-results.txt”
• “Refactor auth.ts to use async/await instead of callbacks”

Send the instruction via Telegram, get the dispatch confirmation, and check back in 10–30 minutes.

Chained Instructions

Because tmux is just passing keystrokes, you can send follow-up messages as Claude Code is working. If you started a task and realize you need to add a constraint, just send another message.

Status Checks

The /status command in the bridge script tells you which tmux sessions are running. You can extend this with more commands:

• /attach — get a summary of what Claude Code is currently doing (requires output capture)
• /cancel — send Ctrl+C to the Claude session
• /history — read recent output from a log file

Notifications on Completion

For very long tasks, add a notification back to Telegram when Claude Code finishes. This requires either polling the tmux output or having Claude Code itself send a message when done — you can instruct it to do this as part of the task prompt.

---

Extend This Further With MindStudio

The Telegram-to-Claude-Code bridge is powerful for code-focused tasks. But AI agents often need to do more than write code — they need to send emails, query APIs, search the web, or trigger workflows in other tools.

That’s where MindStudio’s Agent Skills Plugin fits in. It’s an npm SDK (@mindstudio-ai/agent) that gives any agent — including Claude Code — access to 120+ typed capabilities as simple method calls. Instead of building each integration yourself, you call methods like:

await agent.sendEmail({ to: 'team@company.com', subject: 'Task complete', body: result });
await agent.searchGoogle({ query: 'latest Next.js docs' });
await agent.runWorkflow({ workflowId: 'my-data-pipeline' });

The plugin handles auth, rate limiting, and retries. Claude Code focuses on reasoning and execution; MindStudio handles the infrastructure.

If you’re building a mobile AI agent setup that needs to do more than code — trigger business workflows, generate images, post updates, or interact with external services — combining the Telegram interface with MindStudio’s capabilities is a natural progression.

You can try MindStudio free at mindstudio.ai.

---

Troubleshooting Common Problems

Messages Aren’t Reaching the Tmux Session

Check that the session name in your bridge script matches exactly. Run tmux list-sessions to confirm. Session names are case-sensitive.

Also verify that Claude Code is actually running and waiting for input inside the session. Attach and check manually.

The Bridge Script Crashes After Idle Time

Polling-based Telegram bots can sometimes disconnect. Wrap the script in a process manager like PM2:

npm install -g pm2
pm2 start bridge.js --name telegram-bridge
pm2 startup  # auto-restart on reboot

Claude Code Exits Unexpectedly

Claude Code may time out or exit after completing a task, especially in non-interactive scenarios. You can add a watchdog script that restarts it if the process isn’t running:

# Add to your bridge.js or a separate watcher
exec(`tmux list-panes -t ${TMUX_SESSION} -F '#{pane_current_command}'`, (err, stdout) => {
  if (!stdout.includes('claude')) {
    exec(`tmux send-keys -t ${TMUX_SESSION} 'claude' Enter`);
  }
});

Bot Responds to Other People’s Messages

Double-check that TELEGRAM_CHAT_ID is set correctly and that the comparison in the message handler is using === or the strict integer check. Print msg.chat.id to the console during testing to verify.

Output Isn’t Being Captured

The bridge script above doesn’t capture Claude Code’s terminal output — it only dispatches commands. To capture output, you’d use tmux capture-pane:

tmux capture-pane -pt claude-agent -S -100

This returns the last 100 lines of the session. You can send this back to Telegram on demand by adding a /output command to the bridge.

---

FAQ

Does this work with Claude Code running on a remote server?

Yes — in fact, a remote server is the ideal setup. Run both tmux sessions on your server, run the bridge script there too, and everything stays alive regardless of what your local machine is doing. You SSH in when you need to inspect things directly, and use Telegram for everything else.

Is this secure? Anyone with the bot token can send commands.

The bridge script uses your chat ID as an allowlist. Only messages from your specific Telegram account get forwarded to Claude Code. Your bot token should be kept secret — don’t commit it to a repo. For extra security, you can add IP allowlisting at the server level or use Telegram’s privacy settings to prevent others from starting conversations with your bot.

Can I use this on iOS or Android without a VPN?

Yes. Telegram works over standard HTTPS, so there’s no VPN needed. Your phone talks to Telegram’s servers, your bridge script polls Telegram’s servers, and the two never need a direct connection. This works on any network.

What kinds of tasks is this best suited for?

Long-running, autonomous tasks that don’t require interactive back-and-forth. Code refactoring, file generation, running test suites, automated code review passes, script writing, and documentation generation all work well. Tasks that need frequent human judgment mid-execution are harder to manage remotely.

Can I send files or screenshots through Telegram to Claude Code?

Not with the basic setup above. The bridge handles text only. Extending it to handle photo or document uploads is possible — Telegram’s bot API supports receiving file URLs, and you could pass those paths to Claude Code. But it requires additional handling in the bridge script.

Does this work with other AI coding tools besides Claude Code?

The tmux-based pattern works with any CLI tool that accepts keyboard input and runs in a terminal. You could wire up the same bridge to Aider, Continue, or any other terminal-based AI coding tool. The Telegram layer doesn’t care what’s running in the tmux session.

---

Key Takeaways

• Tmux keeps your Claude Code session alive even when you disconnect — it’s the foundation of any reliable remote agent setup.
• A Telegram bot gives you a secure, mobile-friendly interface to dispatch tasks and receive confirmations from anywhere.
• The bridge script is simple Node.js — a few dozen lines to connect the two systems together.
• Chat ID filtering ensures only you can interact with your agent.
• For tasks beyond code, MindStudio’s Agent Skills Plugin extends Claude Code with 120+ capabilities like email, web search, and workflow execution.
• A dedicated server or VPS makes the setup truly reliable — no dependence on your laptop being awake.

This setup takes an afternoon to configure properly. Once it’s running, you can queue up AI tasks from your phone during a commute, a meeting, or from bed — and come back to finished work.