Claude Code Telegram Bot est un projet open source qui fournit un accès distant à Claude Code à travers l'application de messagerie Telegram. Il permet aux développeurs d'utiliser un langage naturel pour collaborer sur des projets de code, exécuter des opérations sur les fichiers et gérer des sessions de travail, le tout depuis n'importe quel appareil disposant de Telegram. Ce bot résout le problème de l'accès limité à Claude Code, qui est généralement confiné à un terminal local, en offrant une solution légère et accessible.

Principales caractéristiques

• Accès mobile et multi-appareils : Interaction avec Claude Code depuis des smartphones, tablettes ou tout autre apppareil supportant Telegram, sans nécessiter de client SSH ou de bureau à distance.
• Mode conversationnel et commandes : Deux modes d'interaction – le mode Agentic (par défaut) qui utilise le dialogue naturel, et le mode Classic qui offre des commandes textuelles pour des actions spécifiques.
• Persistance des sessions : Les sessions de travail sont sauvegardées par utilisateur et par répertoire de projet, permetttant de reprendre une conversation ultérieurement ou depuis un autre appareil.
• Événements et automatisation : Intégration avec des webhooks (comme GitHub), des tâches planifiées via cron, et des notifications push pour des workflows automatisés.
• Sécurité et contrôle : Mécanismes incluant des listes blanches d'utilisateurs, des sandboxes de répertoires, des limites de débit et des journaux d'audit pour une utilisation sécurisée.

Scénarios d'utilisation

Ce bot est particulièrement utile dans plusieurs situations :

• Dévelpopement mobile léger : Effectuer des modifications rapides, lancer des tests ou consulter l'état d'un projet directement depuis un téléphone.
• Collaboration sur un projet partagé : Plusieurs utilisateurs peuvent accéder au même serveur hébergeant Claude Code via leurs identifiants Telegram, chacun avec ses propres répertoires autorisés.
• Intégration CI/CD : Recevoir des événements de GitHub (comme les pull requests) pour des actions automatiques telles que la révision de code ou la génération de résumés.
• Tâches planifiées : Exécuter des vérifications régulières du code, des mises à jour de dépendances ou des rapports via le planificateur intégré.

Démarrage rapide

Prérequis : Python 3.11+, Claude Code CLI installé et authentifié, un token de bot Telegram obtenu via @BotFather.

Installation

# Via uv (recommandé pour l'isolation des dépendances)
uv tool install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

# Alternative avec pip
pip install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

Configuration

# Créer un fichier .env à partir de l'exemple
cp .env.example .env

# Modifier .env avec les paramètres obligatoires :
# TELEGRAM_BOT_TOKEN=...        # Jeton d'accès du bot
# TELEGRAM_BOT_USERNAME=...     # Nom d'utilisateur du bot
# APPROVED_DIRECTORY=...        # Répertoire racine pour les projets, ex. /home/utilisateur/projets
# ALLOWED_USERS=123456789       # Identifiants Telegram des utilisateurs autorisés (séparés par des virgules)

Pour obtenir votre identifiant Telegram, envoyez un message à @userinfobot dans l'application Telegram.

Lancement

# Exécuter le bot en mode production
make run

# Exécuter avec les logs de débogage activés
make run-debug

Envoyez un message à votre bot dans Telegram pour commencer une session.

Détails techniques

Architecture

Le bot agit comme un intermédiaire entre Telegram et Claude Code. Il reçoit les messages de l'utilisateur, les traite via l'API Claude Code (soit par SDK, soit via CLI), et renvoie les résultats formatés à Telegram. Les opérations sur les fichiers et les commandes sont exécutées dans le répertoire autorisé sur le serveur.

Configuration avancée

Au-delà des paramètres de base, le bot offre de nombreuses options de personnalisation :

• Modes de fonctionnement : Basculer entre le mode Agentic et Classic via la variable AGENTIC_MODE.
• Contrôle des outils : Limiter les outils Claude Code accessibles avec CLAUDE_ALLOWED_TOOLS.
• Événements externes : Activer un serveur d'API pour les webhooks (ENABLE_API_SERVER=true) avec authentification sécurisée.
• Planification : Configurer des tâches récurrentes avec des expressions cron et définir des canaux de notification via NOTIFICATION_CHAT_IDS.
• Sécurité renforcée : Appliquer des limites de débit (RATE_LIMIT_REQUESTS), des plafonds de coûts (CLAUDE_MAX_COST_PER_USER) et activer les journaux d'audit.

Consultez la documentation complète dans les fichiers docs/configuration.md et docs/tools.md pour une liste exhaustive des options.

Résolution de problèmes courants

• Le bot ne répond pas : Vérifiez le token Telegram, les identifiants dans ALLOWED_USERS, et assurez-vous que Claude Code CLI est accessible. Utilisez make run-debug pour inspecter les logs.
• Erreurs de Claude Code : Pour le mode SDK, vérifiez l'authentification avec claude auth status. Pour le mode CLI, assurez-vous que la commande claude est fonctionnelle et que les outils sont autorisés.
• Coûts élevés : Ajustez la limite de coûts par utilisateur, utilisez la commande /status dans Telegram pour suivre la consommation, et optimisez les requêtes.

Comparaison avec d'autres solutions

Par rapport à une utilisation locale de Claude Code ou à une connexion SSH directe, ce bot offre une flexibilité accrue pour l'accès mobile et la persistance des sessions, bien qu'il nécessite une configuration initiale du serveur. Il est idéal pour les développeurs individuels ou les petites équipes cherchant une solution d'accès distant simple et intégrée à Telegram.

Ressources et liens

Le projet est hébergé sur GitHub avec une documentation détaillée. Les utilisateurs sont encouragés à installer une version taguée pour la stabilité. Pour plus d'informations sur Claude Code, consultez la documentation officielle d'Anthropic.