Immagina di essere in viaggio, lontano dal tuo computer, e dover urgentemente fare un fix al codice o analizzare un bug. Con Claude Code Telegram Bot, il tuo smartphone diventa un vero terminale di sviluppo con l'assistenza AI di Claude. In questa guida completa vediamo come installare, configurare e sfruttare al massimo questo potente strumento open source.
Il progetto claude-code-telegram è un bot Telegram che fa da ponte tra la popolare app di messaggistica e Claude Code, permettendoti di interagire con i tuoi progetti da qualsiasi dispositivo. Perfetto per code review in mobilità, quick fix durante i viaggi, o semplicemente per avere assistenza AI quando sei lontano dalla tua postazione di lavoro.
Cos'è Claude Code Telegram Bot e Perché Usarlo
Claude Code Telegram Bot è un progetto open source che trasforma Telegram in un'interfaccia remota per Claude Code. A differenza di altri bot che semplicemente chiamano le API di Claude per rispondere a domande, questo bot offre accesso completo alle funzionalità di Claude Code, inclusa la navigazione delle directory, la gestione dei file e la persistenza delle sessioni.
Le caratteristiche principali includono la possibilità di chattare con Claude riguardo ai tuoi progetti, navigare le directory e gestire file da remoto, mantenere il contesto tra le conversazioni grazie alla persistenza delle sessioni, e beneficiare di un sistema di sicurezza enterprise-grade con autenticazione multi-layer e sandboxing delle directory.
Requisiti di Sistema
Prima di iniziare l'installazione, assicurati di avere i seguenti prerequisiti sul tuo sistema. Avrai bisogno di Python 3.9 o superiore, Poetry per la gestione delle dipendenze Python, Claude Code CLI installato e configurato sul tuo sistema, e un token bot Telegram ottenuto da BotFather.
Se non hai ancora installato Claude Code, ti consiglio di leggere prima la nostra guida comparativa su Claude Code per capire le differenze con altre soluzioni di AI coding.
Creare il Bot Telegram con BotFather
Il primo passo è creare il tuo bot Telegram personale. Apri Telegram e cerca @BotFather, il bot ufficiale per la creazione di altri bot. Invia il comando /newbot e segui le istruzioni per assegnare un nome e uno username al tuo bot. Lo username deve terminare con "bot", per esempio "mio_claude_bot".
Una volta completata la creazione, BotFather ti fornirà un token che assomiglia a qualcosa come 1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Questo token è fondamentale e va conservato in modo sicuro, poiché rappresenta l'accesso completo al tuo bot.
Per ottenere il tuo Telegram User ID, necessario per la whitelist di sicurezza, puoi messaggiare @userinfobot su Telegram. Ti risponderà immediatamente con il tuo ID numerico.
Installazione Passo Passo
L'installazione del bot richiede pochi comandi da terminale. Inizia clonando il repository ufficiale con il comando git clone https://github.com/RichardAtCT/claude-code-telegram.git, poi entra nella directory con cd claude-code-telegram.
Se non hai ancora Poetry installato, puoi farlo con curl -sSL https://install.python-poetry.org | python3 -. Successivamente, installa tutte le dipendenze di sviluppo eseguendo make dev. Questo comando si occuperà di creare l'ambiente virtuale e installare tutti i pacchetti necessari.
Configurazione del File Environment
Copia il file di esempio con cp .env.example .env e modificalo con il tuo editor preferito. La configurazione minima richiede quattro variabili fondamentali.
Imposta TELEGRAM_BOT_TOKEN con il token ricevuto da BotFather, TELEGRAM_BOT_USERNAME con lo username del tuo bot senza la chiocciola, APPROVED_DIRECTORY con il percorso assoluto della directory dei tuoi progetti, e ALLOWED_USERS con il tuo Telegram User ID.
Autenticazione Claude
Per l'autenticazione con Claude hai due opzioni. La prima e raccomandata è utilizzare il login CLI esistente: se hai già autenticato Claude Code sul tuo sistema con il comando claude e seguito il processo di login, il bot utilizzerà automaticamente quelle credenziali.
In alternativa, puoi usare direttamente una API key di Anthropic. Ottieni la chiave dalla Console Anthropic e aggiungila al file .env come ANTHROPIC_API_KEY. Tieni presente che l'uso dell'API key comporta costi per token, mentre l'autenticazione CLI sfrutta il tuo abbonamento esistente.
Avviare il Bot
Per avviare il bot in modalità debug, utile durante la configurazione iniziale, usa make run-debug. Per l'uso in produzione, il comando è semplicemente make run. Il bot mostrerà i log nel terminale, permettendoti di verificare che tutto funzioni correttamente.
A questo punto, apri Telegram, cerca il tuo bot e invia il comando /start. Se tutto è configurato correttamente, riceverai un messaggio di benvenuto.
Comandi Disponibili e Utilizzo Pratico
Il bot offre un'interfaccia simile a un terminale, con comandi familiari per chi lavora già da riga di comando. I comandi di navigazione includono /ls per elencare i file nella directory corrente, /cd nomeprogetto per cambiare directory, /pwd per mostrare la directory corrente, e /projects per visualizzare i progetti disponibili.
Gestione delle Sessioni
Per la gestione delle sessioni Claude, usa /new per iniziare una nuova sessione, /continue per riprendere la sessione precedente opzionalmente con un messaggio, /end per terminare la sessione corrente, /status per vedere lo stato e l'utilizzo, e /export per esportare la sessione in formato Markdown, HTML o JSON.
Funzionalità Avanzate
Il comando /git mostra informazioni sul repository Git, inclusi status, diff e log. Il comando /actions presenta azioni rapide contestuali come eseguire test, formattare il codice o installare dipendenze.
Esempi Pratici di Utilizzo
Vediamo alcuni scenari reali di utilizzo del bot. Per navigare in un progetto e chiedere assistenza, la conversazione potrebbe essere così: invii "cd my-web-app" e il bot risponde indicando il cambio directory. Poi invii "ls" e vedi la struttura del progetto. Infine chiedi "Puoi aiutarmi ad aggiungere TypeScript a questo progetto?" e Claude analizza la struttura e fornisce istruzioni dettagliate per la migrazione.
Analisi di File e Archivi
Una delle funzionalità più potenti è la possibilità di inviare file direttamente al bot per l'analisi. Puoi caricare singoli file di codice, configurazioni o documenti e Claude li analizzerà immediatamente. Se invii un archivio ZIP o TAR, il bot lo estrae e analizza la struttura del progetto, identificando linguaggi, framework e entry point.
Per gli screenshot e le immagini, il bot genera automaticamente prompt intelligenti per l'analisi. Questo è particolarmente utile per condividere mockup di UI o diagrammi architetturali quando sei in movimento.
Integrazione Git
Il comando /git fornisce una panoramica completa del repository, mostrando il branch corrente, i file modificati, i commit recenti e quanto sei indietro rispetto al branch principale. Puoi visualizzare diff, log e modifiche con pulsanti interattivi.
Configurazioni Avanzate
Per personalizzare ulteriormente il bot, puoi modificare diverse impostazioni nel file .env. La variabile USE_SDK impostata a true usa il Python SDK di Anthropic (default), mentre false utilizza il subprocess CLI. CLAUDE_MAX_COST_PER_USER imposta il limite di spesa per utente in dollari, CLAUDE_TIMEOUT_SECONDS definisce il timeout per le operazioni, e CLAUDE_ALLOWED_TOOLS specifica quali strumenti Claude può utilizzare.
Per il rate limiting, RATE_LIMIT_REQUESTS imposta il numero massimo di richieste per finestra temporale, mentre RATE_LIMIT_WINDOW definisce la durata della finestra in secondi. Puoi anche abilitare o disabilitare funzionalità specifiche come l'integrazione Git, l'upload di file e le azioni rapide.
Sicurezza e Best Practice
Il bot implementa un sistema di sicurezza multi-layer che include autenticazione basata su whitelist degli utenti, isolamento delle directory con sandboxing rigoroso, rate limiting con algoritmo token bucket, logging completo delle azioni per audit, e validazione degli input contro attacchi di injection e path traversal.
È importante ricordare che Telegram non offre crittografia end-to-end per le conversazioni con i bot. Tutti i messaggi passano attraverso i server di Telegram non crittografati. Per questo motivo, non dovresti mai condividere informazioni sensibili come password, API key o credenziali attraverso il bot.
Per un livello aggiuntivo di sicurezza, considera di eseguire il bot in un container Docker, dove puoi controllare esattamente quali file e risorse di rete sono accessibili. Puoi anche configurare i permessi di Claude Code e utilizzare gli hooks per aggiungere step di verifica per operazioni sensibili.
Troubleshooting Comune
Se il bot non risponde, verifica che il token Telegram sia corretto, controlla che il tuo User ID sia nella lista degli utenti autorizzati, assicurati che Claude Code CLI sia installato e accessibile, e controlla i log del bot per messaggi di errore.
Per errori di permesso, verifica che il percorso in APPROVED_DIRECTORY esista e sia leggibile, assicurati che il processo del bot abbia i permessi necessari sul filesystem, e controlla che i percorsi non contengano caratteri speciali.
Se l'integrazione con Claude non funziona, in modalità SDK controlla l'autenticazione CLI con claude auth status, verifica che l'API key sia configurata se non usi l'auth CLI, e assicurati che l'account abbia crediti sufficienti.
Alternative e Progetti Correlati
Esistono altri progetti simili che potrebbero interessarti. Il bot di linuz90 offre funzionalità aggiuntive come messaggi vocali con trascrizione tramite Whisper e thinking esteso. Il progetto di hanxiao usa un approccio diverso con tmux e Cloudflare Tunnel per il bridging.
Per chi cerca solo notifiche da Claude Code senza l'interazione completa, esistono hook che inviano aggiornamenti a Telegram quando Claude termina di lavorare su un task, perfetti per operazioni di lunga durata. Approfondisci le potenzialità dell'AI coding con la nostra guida su Codex Agent Loop di OpenAI.
Leggi anche
- Claude Code 2.1: 16 Novità che Rivoluzionano lo Sviluppo AI
- Claude Code vs OpenCode: Guida Completa AI Coding 2026
- Codex Agent Loop di OpenAI: Guida Tecnica Completa 2026
- Claude Code Gratis con Ollama: Guida Completa ai Modelli Locali
- GitHub Copilot CLI e SDK: Guida Completa 2026
Conclusioni
Claude Code Telegram Bot rappresenta un cambio di paradigma nel modo in cui gli sviluppatori possono interagire con i loro progetti. La possibilità di avere un assistente AI completo accessibile da smartphone apre scenari di produttività impensabili fino a poco tempo fa: code review durante il tragitto verso l'ufficio, quick fix mentre sei in fila, o semplicemente la tranquillità di poter intervenire su un problema urgente ovunque tu sia.
Il progetto è attivamente sviluppato con nuove funzionalità in arrivo come streaming delle risposte in tempo reale, integrazione completa con Claude Vision API, e un sistema di plugin per estensioni di terze parti. Se stai cercando di portare il tuo workflow di sviluppo al livello successivo, questo bot merita sicuramente una prova.
Hai bisogno di aiuto per integrare strumenti di AI nel tuo workflow di sviluppo? Contattami per una consulenza personalizzata sulle soluzioni di sviluppo web app più adatte alle tue esigenze.
