Control Claude Code From Your Phone: ClaudeBot Exposed

Control Claude Code From Your Phone: ClaudeBot Exposed

What if your most powerful coding assistant was trapped in your terminal—and you could set it free?

Picture this: You're commuting on a crowded train, lying in bed half-asleep, or sitting in a café without your laptop. Suddenly, a brilliant idea strikes. You need to refactor that messy API endpoint, analyze a log file, or generate documentation for yesterday's commit. But your terminal is miles away, locked behind your desktop's login screen. The moment passes. The idea fades. Another opportunity lost to the tyranny of physical proximity.

Sound painfully familiar?

Here's the dirty secret most developers won't admit: we're still shackled to our machines. Despite living in an age of cloud computing and remote everything, our AI coding tools remain stubbornly local. Claude Code—Anthropic's revolutionary CLI assistant—can architect entire applications, debug complex systems, and write production-ready code. Yet it sits there, useless, the moment you step away from your keyboard.

Until now.

Enter ClaudeBot, the open-source bridge that transforms your smartphone into a remote control for Claude Code. Built by developer Philo-Li, this system tray application doesn't just extend Claude Code—it liberates it. Send a Telegram message from anywhere on Earth, and watch as Claude Code executes on your machine, streaming results back in real-time. No SSH tunnels. No VPN configurations. No complex infrastructure. Just pure, effortless remote coding power.

In this deep dive, I'll expose exactly how ClaudeBot works, why developers are quietly abandoning their old remote workflows, and how you can deploy this secret weapon in under ten minutes. The future of mobile-first development starts here—and it's surprisingly simple.

What Is ClaudeBot?

ClaudeBot is a cross-platform system tray application that creates a secure, bidirectional bridge between your mobile device and the Claude Code CLI running on your computer. Born from the frustration of wanting to leverage Claude's capabilities beyond the desktop, this open-source project by Philo-Li solves a deceptively simple problem with elegant engineering.

At its core, ClaudeBot operates as a local proxy and orchestrator. It runs silently in your system tray, maintaining persistent connections to both Telegram's Bot API and optionally the Dopamind cloud queue. When you send a message, ClaudeBot receives it, invokes Claude Code in your configured working directory, captures the output stream, and pipes results back to your phone—with full session context preserved across interactions.

The project has gained rapid traction in developer communities for three reasons. First, it requires zero infrastructure investment—no servers to provision, no domains to configure, no SSL certificates to manage. Second, it leverages Telegram's robust, encrypted messaging infrastructure, which most developers already use. Third, it maintains the full power of Claude Code rather than dumbing it down for mobile; you're not getting a limited API wrapper, you're getting the complete terminal experience distilled into conversational messages.

ClaudeBot supports Windows, macOS, and Linux through native installers and portable executables. The auto-update mechanism ensures you benefit from continuous improvements without manual intervention. And with MIT licensing, the community is already extending it with custom integrations and workflow automations.

What makes ClaudeBot genuinely transformative is its session memory architecture. Unlike simple command-forwarding tools that treat each message in isolation, ClaudeBot maintains conversation context. Ask it to "refactor the authentication module," then follow up with "now add rate limiting to that same file," and Claude understands the continuity. This isn't remote execution—it's remote collaboration with a persistent AI pair programmer.

Key Features That Separate ClaudeBot From Amateur Solutions

Let's dissect what makes ClaudeBot production-ready rather than a weekend hack project.

Native Telegram Bot Integration. ClaudeBot implements the full Telegram Bot API for message handling, not some brittle webhook workaround. Messages are received via long-polling with automatic reconnection, ensuring reliability even on unstable networks. The bot supports markdown^{↗ Smart Converter} formatting in responses, so code blocks render beautifully on your phone screen.

Dopamind Cloud Queue Support. For teams and power users, ClaudeBot integrates with Dopamind's task queue infrastructure. This enables scenarios like: queue a complex analysis job from your phone, let it run for hours, receive notification when complete. The device token authentication (dpm_... format) ensures secure, scoped access without exposing your Telegram credentials.

Persistent Session Memory. Here's where engineering meets magic. ClaudeBot maintains conversation state using Claude Code's native session mechanisms. Context windows, token usage, and conversation history survive across messages, days, even application restarts. The /new command gives you explicit control to reset when needed, while /usage provides transparency into costs and context consumption.

Real-Time Progress Streaming. Long-running tasks don't leave you guessing. ClaudeBot captures Claude Code's streaming output and forwards progress indicators to Telegram. Watch as files are analyzed, tests execute, or documentation generates—all from your phone's notification shade.

Cross-Platform System Tray Integration. Built on Electron, ClaudeBot provides native system tray behavior across all platforms. On Windows, it integrates with the notification area. On macOS, it appears in the menu bar. Linux users get AppImage and .deb packages with proper desktop integration. The tray menu exposes status, controls, and configuration without cluttering your taskbar.

Automatic GitHub Releases Integration. The auto-updater polls GitHub Releases at startup, downloads updates in background threads, and prompts for installation. This means security patches and feature improvements reach users without manual package management—a critical capability for a tool handling API tokens.

Granular Access Control. The ALLOWED_USER_IDS configuration prevents unauthorized access to your Claude Code instance. Only specified Telegram users can invoke commands, making this viable for shared workstations or team deployments where multiple developers need controlled access.

Four Real-World Scenarios Where ClaudeBot Dominates

Scenario 1: The Emergency Production Fix

It's 2 AM. PagerDuty screams. You're three hours from your workstation, but your phone is in hand. With ClaudeBot, you SSH isn't even necessary—send /setdir /var/www/production, then "investigate the 500 errors in the payment webhook and implement a fix." Claude Code analyzes logs, identifies the race condition, writes the patch, and you review the diff from bed. Approve with "commit and push to hotfix branch." Crisis resolved before you reach your desk.

Scenario 2: The Commuting Architect

Your best architectural insights strike during dead time. On the train, you message ClaudeBot: "design a caching layer for the user service using Redis with fallback to database, include circuit breaker pattern." By the time you reach the office, a complete implementation with tests awaits in your working directory. You don't lose creative momentum to physical constraints.

Scenario 3: The Distributed Team Lead

Your junior developer is blocked on a complex TypeScript generics issue. They're in Bangalore, you're in Berlin, and it's their 3 AM. Rather than scheduling a painful sync, you message ClaudeBot with context: "review the type definitions in src/types/api.ts and suggest fixes for the generic inference failure on line 47." The detailed explanation lands in their morning, unblocking them without real-time coordination overhead.

Scenario 4: The Long-Running Analysis

You need to process six months of log files for security audit patterns. From your phone, queue the task via Dopamind integration: "analyze /var/log/app for SQL injection attempts, generate summary report with timestamps and IP addresses." ClaudeBot acknowledges, begins processing, and you receive completion notification with the report attachment. Complex compute tasks become asynchronous workflows you manage from anywhere.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installation, verify you have:

• Claude Code CLI installed and claude command available in your terminal
• Telegram account (free, available on all platforms)
• Node.js 18+ (only if building from source)

Method 1: Prebuilt Installers (Recommended)

Navigate to the Releases page and download for your platform:

Method 2: Build From Source

For developers wanting latest commits or custom modifications:

# Clone the repository
git clone https://github.com/Philo-Li/claudebot.git
cd claudebot

# Install dependencies
npm install

# Run as Electron tray app in development mode
npm run electron:dev

# Or run Telegram bot only (headless, no GUI)
npm start

Build platform-specific installers when ready to distribute:

# Windows: NSIS installer plus portable executable
npm run build:win

# macOS: DMG disk image
npm run build:mac

# Linux: AppImage and Debian package
npm run build:linux

Telegram Bot Configuration

Step 1: Create Your Bot

1. Open @BotFather in Telegram
2. Send /newbot and follow prompts to name your bot
3. Securely save the Bot Token (format: 123456:ABC-DEF...)

Step 2: Identify Your User ID

1. Open @userinfobot
2. Send any message
3. Note your numeric User ID

Step 3: Configure ClaudeBot

Launch ClaudeBot—the settings window appears automatically on first run:

Click Save. The bot starts automatically and appears in your system tray.

Dopamind Integration (Optional)

For cloud queue capabilities:

1. Right-click tray icon → Settings
2. Check Enable Dopamind
3. Enter Device Token from Dopamind app (format: dpm_...)
4. Save and restart

Configuration File Locations

Advanced users can edit .env directly:

# Windows
%APPDATA%\ClaudeBot\.env

# macOS
~/Library/Application Support/ClaudeBot/.env

# Linux
~/.config/ClaudeBot/.env

Real Code Examples: Inside ClaudeBot's Implementation

Let's examine actual code patterns from the repository to understand how ClaudeBot achieves its magic.

Example 1: Running From Source (Development Mode)

The simplest entry point for contributors and customizers:

# Clone the repository from GitHub
git clone https://github.com/Philo-Li/claudebot.git

# Enter project directory
cd claudebot

# Install all Node.js dependencies (Electron, Telegram API, etc.)
npm install

# Launch as Electron tray application with hot-reload for development
npm run electron:dev

# ALTERNATIVE: Run Telegram bot service without Electron GUI
# Useful for servers, headless environments, or minimal resource usage
npm start

What's happening here? The npm run electron:dev command launches Electron with development tooling enabled—hot module replacement, developer tools, and verbose logging. For production deployments or resource-constrained environments, npm start initializes only the Telegram bot service, skipping the Electron renderer process entirely. This dual-mode architecture is why ClaudeBot works equally well on your developer workstation and a headless VPS.

Example 2: Building Cross-Platform Installers

The build system leverages Electron Builder for native packaging:

# Generate Windows installer (NSIS) and portable executable
# Output: dist/ClaudeBot-Setup-x.x.x.exe, dist/ClaudeBot-x.x.x.exe
npm run build:win

# Generate macOS disk image
# Output: dist/ClaudeBot-x.x.x.dmg
npm run build:mac

# Generate Linux packages (AppImage and Debian)
# Output: dist/ClaudeBot-x.x.x.AppImage, dist/claudebots_x.x.x_amd64.deb
npm run build:linux

The engineering insight: Electron Builder handles code signing, auto-update metadata generation, and platform-specific quirks automatically. The NSIS installer provides Windows users familiar wizard-based installation, while the portable .exe requires no installation privileges—critical for corporate environments with restricted software policies. The AppImage format gives Linux users distribution-agnostic execution, while the .deb integrates with Debian-based package managers for automatic dependency resolution.

Example 3: Environment Configuration

ClaudeBot uses a standard .env file for all runtime configuration:

# Telegram Bot API token from @BotFather
# Required for all Telegram functionality
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# Comma-separated whitelist of authorized Telegram users
# Security-critical: prevents unauthorized access to your Claude Code instance
ALLOWED_USER_IDS=12345678,87654321

# Default working directory for Claude Code execution
# All relative paths resolve against this directory
WORK_DIR=/home/user/projects/myapp

# Enable Dopamind cloud queue integration (true/false)
DOPAMIND_ENABLED=true

# Dopamind device authentication token
# Format always begins with 'dpm_' prefix
DOPAMIND_TOKEN=dpm_a1b2c3d4e5f6g7h8i9j0

Security architecture revealed: The ALLOWED_USER_IDS whitelist is ClaudeBot's primary access control mechanism. Even if your Bot Token is compromised, attackers cannot invoke Claude Code without being explicitly authorized. The separation of WORK_DIR from executable location prevents path traversal attacks. Dopamind tokens use a distinct dpm_ prefix for easy validation and rotation. All credentials live outside version control in the system user data directory, following the XDG Base Directory Specification on Linux and equivalent conventions on other platforms.

Example 4: Telegram Interaction Pattern

The user-facing interaction model is deliberately minimal:

# User sends natural language message to their bot
Hey, list the files in the current directory

# ClaudeBot processes:
# 1. Validates sender against ALLOWED_USER_IDS
# 2. Invokes `claude` in configured WORK_DIR
# 3. Streams output via Telegram's message API
# 4. Preserves session context for follow-up messages

# System commands for session management
/new           # Start fresh conversation (clear context)
/stop          # Halt currently executing task
/usage         # Display token consumption and costs
/status        # Show active configuration
/setdir <path> # Temporarily change working directory

Why this design succeeds: The absence of required commands reduces cognitive load—you simply message your bot as you would a colleague. The /new command provides explicit context reset, preventing expensive context window pollution. The /stop command implements cooperative cancellation, sending SIGTERM to Claude Code processes rather than force-killing, which prevents file corruption. The /setdir temporary override enables multi-project workflows without restarting the application.

Advanced Usage & Best Practices

Secure Your Bot Token Like an SSH Key. Your TELEGRAM_BOT_TOKEN grants full control over your bot. Store it in password managers, never commit to repositories, and rotate immediately if compromised. Consider using Telegram's bot privacy mode to prevent group chat exposure.

Optimize Context Window Management. Claude Code's context window is finite and costly. Use /new proactively when switching tasks. Monitor /usage to understand token consumption patterns. For large codebases, use /setdir to scope to specific subdirectories rather than repository roots.

Leverage Dopamind for Team Workflows. Configure multiple ClaudeBot instances with shared Dopamind queues for distributed task processing. Assign device tokens per-project for access segmentation. The polling architecture handles intermittent connectivity gracefully—tasks queue during offline periods and process when connectivity restores.

Automate Working Directory Switching. Create shell aliases or Telegram keyboard shortcuts for frequent /setdir targets. Combine with Git worktrees for parallel branch development: /setdir /projects/myapp-feature-auth then "implement JWT refresh tokens."

Monitor Auto-Update Behavior. While convenient, verify update integrity in security-sensitive environments. The GitHub Releases mechanism uses HTTPS and checksum validation, but paranoid deployments may disable auto-update and manually verify release signatures.

ClaudeBot vs. Alternatives: Why Developers Are Switching

The verdict: ClaudeBot occupies a unique sweet spot—zero infrastructure cost, full Claude Code capability, and mobile-optimized UX through Telegram's polished interface. SSH solutions require technical sophistication and provide poor mobile experiences. Direct API access sacrifices Claude Code's agentic capabilities for basic completion. Cloud IDEs introduce ongoing costs and vendor lock-in.

Frequently Asked Questions

Is ClaudeBot officially affiliated with Anthropic or Claude Code?

No. ClaudeBot is an independent open-source project by Philo-Li. It requires separately installed and authenticated Claude Code CLI. Anthropic does not endorse or support third-party integrations, though the MIT license permits this usage.

Can multiple people use my ClaudeBot instance safely?

Yes, through the ALLOWED_USER_IDS whitelist. Only specified Telegram users can invoke commands. However, all users share the same Claude Code session and working directory—there is no multi-tenancy isolation. For true separation, run separate ClaudeBot instances with distinct configurations.

What happens if my phone loses connection during a long task?

ClaudeBot continues executing on your machine. Results are sent when connectivity restores, or you can check status by messaging /status upon reconnection. The /stop command cancels running tasks if needed.

Does ClaudeBot store my Telegram messages or Claude Code outputs?

Message content passes through Telegram's infrastructure per their privacy policy. ClaudeBot processes messages ephemerally for command execution. Review the source code for specific data handling—being open-source, transparency is verifiable.

Can I use ClaudeBot without Telegram?

Partially. The Dopamind integration provides an alternative message queue, but Telegram remains the primary interface. For custom integrations, the source code is available for modification under MIT license.

Is there a Docker^{↗ Bright Coding Blog} deployment option?

Not officially provided, but the Node.js/Electron architecture is containerizable. Community contributions for Docker packaging would be welcomed—check the repository for discussions.

How do I troubleshoot connection issues?

Verify: (1) Bot Token correctness with @BotFather, (2) User ID accuracy from @userinfobot, (3) Claude Code CLI accessibility in PATH, (4) Firewall rules allowing Telegram API access. Enable verbose logging in development mode for detailed diagnostics.

Conclusion: Your Code, Unchained

ClaudeBot represents more than a convenience utility—it's a fundamental shift in how we interact with AI coding assistants. By decoupling Claude Code's intelligence from physical keyboard proximity, it transforms every moment of downtime into productive development time. The commute becomes architecture sessions. Waiting rooms become debugging opportunities. Bedtime inspiration becomes committed code before sleep.

The implementation impresses with its engineering discipline: cross-platform native packaging, secure credential management, graceful degradation under connectivity stress, and clean separation between transport (Telegram/Dopamind) and execution (Claude Code). This isn't a fragile hack held together with webhooks and wishful thinking—it's production infrastructure you can trust with real projects.

My assessment? ClaudeBot earns immediate adoption for any developer already using Claude Code. The setup friction is negligible, the mobile experience is genuinely delightful through Telegram's mature interface, and the cost—free, running on your existing hardware—is unbeatable. The Dopamind integration hints at even broader team workflow possibilities as the ecosystem matures.

The repository awaits at github.com/Philo-Li/claudebot. Download the latest release, spend five minutes in configuration, and experience the liberation of truly remote AI pair programming. Your best coding moments shouldn't require you to be sitting at your desk—they should find you wherever inspiration strikes.

Stop tethering your intelligence to your machine. Set ClaudeBot free.