Turn Claude Code into a Portable AI Agent with Telegram

Stop being chained to your desk. Here's how to run Claude Code remotely from anywhere using Telegram — with just three lines of configuration.

---

The Problem with Being a Developer on the Go

You know the scenario: you're away from your workstation, an idea strikes, or something needs to get done — and your powerful local AI setup is sitting idle at home while you fumble with a phone screen. Running Claude Code on a remote Mac or Linux machine from a coffee shop, airport, or anywhere outside your home office has historically meant SSH tunnels, VPNs, or clunky mobile terminals.

There's a cleaner way.

Developer @runes_leo recently shared a setup that turns Claude Code into a fully portable AI agent you can interact with from anywhere — using nothing more than a Telegram Bot and the Claude Agent SDK. No heavy middleware, no complex infrastructure. Just clone a repo, configure three values, and you're running remote AI workflows from your phone.

---

Why Telegram? Why Not Something More "Developer-Friendly"?

Telegram might not be the first tool that comes to mind for developer automation, but it earns its place here for practical reasons:

• Universal availability — Telegram runs on iOS, Android, and every desktop OS. You already have it.
• Bot API maturity — The Telegram Bot API is stable, well-documented, and requires no server infrastructure to poll for messages.
• Message threading and file support — You can send code snippets, receive file outputs, and maintain conversational context natively.
• No port forwarding required — Your home Mac connects outbound to Telegram's servers. Nothing is exposed to the public internet.

The alternative explored in the original post — Clawdbot — was ruled out as "too heavy." The insight here is that Claude Agent SDK already provides everything you need programmatically; Telegram just becomes the communication channel. You don't need a full-featured wrapper when a lightweight integration does the job.

---

Setting Up Your Remote Claude Agent: The Full Walkthrough

The core stack is minimal on purpose: Claude Agent SDK handles the AI reasoning and tool execution, and a Telegram Bot acts as the interface layer between you and the agent running on your home machine.

Step 1 — Clone the Open Source Project

Start by cloning the integration repository on your host machine (the Mac or Linux box running Claude Code):

git clone https://github.com/your-target-repo/claude-telegram-agent
cd claude-telegram-agent
npm install   # or pip install -r requirements.txt depending on implementation

The repository wires together the Telegram Bot API listener and the Claude Agent SDK invocation in a minimal event loop: message in → agent processes → response out.

Step 2 — Create Your Telegram Bot

Open Telegram and start a conversation with @BotFather. This is Telegram's official bot management interface.

/start
/newbot

Follow the prompts — give your bot a name and a username. BotFather will issue you a Bot Token, a string that looks like:

7491823056:AAFxyz_example_token_string_here

Copy it. This is the credential your host machine will use to connect to Telegram's API.

Step 3 — Fill in Three Lines of Configuration

Open the project's configuration file (typically a .env or config.yaml):

TELEGRAM_BOT_TOKEN=7491823056:AAFxyz_example_token_string_here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
ALLOWED_USER_ID=123456789

That's it. Three values:

1. TELEGRAM_BOT_TOKEN — from BotFather
2. ANTHROPIC_API_KEY — your Anthropic API key from console.anthropic.com
3. ALLOWED_USER_ID — your personal Telegram user ID (find yours by messaging @userinfobot)

The ALLOWED_USER_ID field is critical for security. It whitelist-restricts the bot so that only your account can trigger agent actions — nobody else can accidentally (or maliciously) run code on your machine.

Step 4 — Start the Agent

npm start
# or
python main.py

Your host machine is now listening. Open Telegram on your phone, message your bot, and you're issuing instructions to Claude Code running on your home hardware — from anywhere with mobile data.

---

Real-World Use Cases for a Remote Claude Agent

Once this is running, the productivity surface expands considerably. Here's how developers are putting it to work:

Code generation and file creation

"Write a Python script that parses my server logs and summarizes errors by hour. Save it to ~/scripts/log_parser.py"

Claude writes the file directly to your filesystem. No copy-paste from a phone keyboard.

Running background tasks

"Refactor the UserService class in my project to use async/await and run the test suite when done."

The agent executes the task, runs tests, and reports back — while you're on a train.

Research and summarization

"Search the latest Anthropic documentation on tool use and summarize what changed in the past month."

Claude can use web tools or local file access depending on how your agent is configured, then drops a summary into your Telegram chat.

Codebase Q&A

"Look at the authentication middleware in my project and explain how session tokens are being validated."

You get a detailed explanation without needing to open a laptop.

---

Security Considerations Worth Noting

Running an AI agent with code execution capabilities on your home machine does carry responsibility:

• User ID whitelisting is non-negotiable. Enforce it.
• Consider running the agent process under a restricted user account on your Mac, not as your primary admin account.
• If Claude has file system or shell access via tools, be deliberate about which directories are accessible.
• Audit your Telegram bot settings — disable adding it to groups if you don't need that surface.
• Rotate your Anthropic API key if you ever suspect your .env file was exposed.

The architecture is inherently safer than port-forwarding SSH because nothing on your machine is publicly exposed — all communication flows through Telegram's servers over standard outbound HTTPS.

---

Conclusion: Lightweight Beats Feature-Bloated Every Time

The takeaway from @runes_leo's approach isn't just technical — it's philosophical. When you need a portable AI agent, reach for the minimal viable stack. The Claude Agent SDK gives you the reasoning engine. Telegram gives you the interface. Everything else is unnecessary complexity.

From zero to a working remote AI agent in the time it takes to read this post: clone a repo, talk to BotFather, set three environment variables, and start the process. Your Mac becomes a powerful AI workstation you can reach from your pocket.

For developers already using Claude Code heavily in their local workflow, this is the natural next step — remove the location constraint entirely.

---

Have you built something similar or extended this pattern with additional tools or platforms? Share it in the comments or connect with the community at ClawList.io.