cc-telegram

January 13, 2026 · View on GitHub

GitHub: https://github.com/hada0127/cc-telegram

Version History

Remote Claude Code execution via Telegram bot.

Control Claude Code from anywhere using your Telegram app. Create tasks, monitor progress, and receive completion notifications - all from your phone.

Features

Remote Task Execution: Send coding tasks to Claude Code via Telegram
Parallel Execution: Run multiple tasks simultaneously (configurable)
Priority System: Urgent, High, Normal, Low priority levels
Auto-Retry: Automatic retry on failure with configurable attempts
Real-time Status: Monitor task progress and Claude's output
Log Rotation: Automatic cleanup of old logs and completed tasks

Requirements

Node.js 18.0.0 or higher
Claude Code CLI installed and authenticated
Telegram account

Installation

npx cc-telegram

Or install globally:

npm install -g cc-telegram
cc-telegram

Initial Setup

On first run, cc-telegram will guide you through the setup process:

Create a Telegram Bot
- Open Telegram and search for @BotFather
- Send /newbot and follow the prompts
- Copy the bot token provided
Enter Bot Token
- Paste your bot token when prompted
- The tool will verify the token is valid
Link Your Account
- Open your new bot in Telegram
- Send /start to the bot
- The CLI will detect your message and display your chat ID
- Enter the chat ID to confirm
Configure Settings
- Set default retry count (recommended: 15)
- Enable/disable parallel execution
- Set max concurrent tasks (if parallel enabled)

Your configuration is stored locally in .cc-telegram/config.json (encrypted).

Usage

After setup, simply run:

npx cc-telegram

The bot will start and listen for commands from your Telegram account.

Telegram Commands

Command	Description
`/new`	Create a new task
`/list`	View pending and in-progress tasks
`/completed`	View completed tasks
`/failed`	View failed tasks
`/status`	Check current execution status and cancel running tasks
`/debug`	View system information
`/cancel`	Cancel task creation flow
`/reset`	Reset all data (with confirmation)

Creating Tasks

Simple Tasks

For one-time execution without completion criteria:

Send /new
Select "Simple (no completion criteria, no retry)"
Enter your requirement
Task is queued immediately

Complex Tasks

For tasks with completion criteria and auto-retry:

Send /new
Select "Complex (with completion criteria and retry)"
Enter your requirement
Enter completion criteria (e.g., "All tests pass")
Select priority level
Choose retry count (10 or custom)

Plan Mode: Complex tasks automatically run Claude in plan mode (--permission-mode plan option). This enables Claude to design an implementation approach before executing, resulting in better outcomes for complex requirements.

File Attachments

You can attach files when entering requirements or completion criteria:

When prompted for requirements/criteria, first send your files (images, documents, etc.)
A confirmation message will appear for each attached file
Then enter your requirements/criteria as text
Attached files will be passed to Claude along with the task

Note: Attached files are automatically deleted when the task is completed, failed, or canceled.

Task Priority

Tasks are executed in priority order:

Priority	Icon	Description
Urgent	:red_circle:	Execute first
High	:orange_circle:	High priority
Normal	:green_circle:	Default priority
Low	:blue_circle:	Execute when idle

Parallel Execution

When enabled during setup, multiple tasks can run simultaneously:

Configure max concurrent tasks (1-10)
Each task shows its ID prefix in console output
/status shows all running tasks with stop buttons to cancel them
Higher priority tasks still get slots first

Canceling Running Tasks

You can cancel tasks that are currently running:

Send /status to view running tasks
Each running task displays a "Stop" button
Click the button to immediately terminate the task
The canceled task will be marked as failed

Console Output (Parallel Mode)

[a1b2c3d4] Starting task...
[e5f6g7h8] Compiling project...
[a1b2c3d4] Tests passed!

Configuration

Configuration is stored in .cc-telegram/config.json:

Setting	Description	Default
`botToken`	Telegram bot token (encrypted)	-
`chatId`	Your Telegram chat ID (encrypted)	-
`debugMode`	Enable debug logging	`false`
`claudeCommand`	Custom Claude CLI command	`null` (auto-detect)
`logRetentionDays`	Days to keep log files	`7`
`defaultMaxRetries`	Default retry count	`15`
`parallelExecution`	Enable parallel execution	`false`
`maxParallel`	Max concurrent tasks	`3`

Custom Claude Command

If Claude CLI is installed in a non-standard location:

{
  "claudeCommand": "npx @anthropic-ai/claude-code"
}

Directory Structure

.cc-telegram/
├── config.json      # Encrypted configuration
├── tasks.json       # Pending task index
├── completed.json   # Completed task index
├── failed.json      # Failed task index
├── tasks/           # Individual task files
├── completed/       # Completed task details
├── failed/          # Failed task details
└── logs/            # Daily log files

Completion Detection

Claude Code signals task completion using special markers:

<promise>COMPLETE</promise> - Task completed successfully
<promise>FAILED</promise> - Task failed with reason

If no signal is detected, the system uses pattern matching to determine success or failure based on output content.

Log Management

Log files are created daily: YYYY-MM-DD.log
Old logs are automatically deleted after logRetentionDays
Completed/failed task files are cleaned up after 30 days

Security

Bot token and chat ID are encrypted using AES-256-GCM
Only messages from your registered chat ID are processed
All data is stored locally in your project directory

Troubleshooting

Bot not responding

Ensure the bot is running (npx cc-telegram)
Check if your chat ID matches the configured one
Verify internet connection

Claude Code not found

Ensure Claude CLI is installed: npm install -g @anthropic-ai/claude-code
Or set a custom command in config: "claudeCommand": "npx @anthropic-ai/claude-code"

Tasks stuck in progress

On restart, orphan tasks are automatically reset to "ready" status
Use /reset to clear all data if needed

License

MIT