TG-Bale/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Project Does

Tele2Bale — transfers files from a Telegram bot to Bale messenger's Saved Messages via a Userbot. Supports files up to 2GB by bypassing Bale's 50MB bot limit through Userbot authentication. Features a file-based queue system, real-time progress updates, Safe Mode (AES-encrypted ZIP before upload), and direct URL downloading.

Running the Project

Install dependencies:

pip install -r requirements.txt

First-time Bale login (interactive — required once to create session.bale):

python3 bale.py

Run the application:

python3 main.py

Architecture

main.py spawns telebot.py and bale.py as separate subprocesses and waits for both. The two components communicate exclusively via files in queue/.

telebot.py (Telegram Bot — Pyrogram)

• Receives files/URLs from users via Telegram bot
• Downloads Telegram media immediately to downloads/ using pyrogram
• Writes tasks to queue/tasks.jsonl (JSONL, append-only)
• Watches queue/status.jsonl via status_watcher() coroutine and edits Telegram messages to reflect upload progress
• Handles /del, /delall, /safemode commands; cancellations written to queue/cancelled.jsonl

bale.py (Bale Userbot Worker — aiobale)

• Pops tasks from queue/tasks.jsonl one at a time (pop_first_task() reads and rewrites the file)
• For direct_url tasks: downloads via requests streaming to downloads/url/
• For local_file tasks: uses the already-downloaded path
• If Safe Mode: wraps file in AES-encrypted ZIP via pyzipper, then deletes the original
• Uploads to Bale via aiobale.Client.send_document() with retry logic (up to 5 attempts, 30-minute timeout)
• Writes progress/status updates to queue/status.jsonl which telebot.py picks up

Queue File Protocol

File	Purpose
queue/tasks.jsonl	Pending tasks; telebot.py appends, bale.py pops from front
queue/status.jsonl	Append-only status updates from bale.py; consumed by telebot.py
queue/processing.json	Single-task file; current in-flight task
queue/deleted.jsonl	Deleted task records for dedup
queue/cancelled.jsonl	Cancellation signals keyed by job_id
queue/failed.jsonl	Failed tasks with error messages

Configuration (.env)

API_ID=          # Telegram API ID (from my.telegram.org)
API_HASH=        # Telegram API Hash
BOT_TOKEN=       # Telegram bot token
BALE_TARGET_ID=  # Bale UID to send files to (Saved Messages ID)

The BALE_PHONE in .env is used during the interactive first-run session setup for aiobale.

Key Constraints

• Userbot required: Bale bot API limits files to 50MB; the Userbot (session.bale) bypasses this.
• Sequential processing: bale.py processes one task at a time to avoid Bale rate limiting/crashes.
• UPLOAD_TIMEOUT is 1800s (30 min) — tune based on server speed and file sizes.
• All user-facing messages in the bot are in Persian (Farsi).