Claude Telegram Supercharged

Substituto direto para o plugin oficial do canal Telegram do Claude Code: transcrição e respostas por voz, histórico e memória em SQLite, threads em grupos, botões inline, mensagens agendadas e um supervisor de daemon.

GitHub

116

Experimente este MCPPatrocinado

Documentação

O plugin oficial do Claude Code para Telegram é bom. Este é melhor.

Começando • Recursos • Modo Agêntico • Referência de Ferramentas • Contribuindo

Claude Telegram Supercharged

Upgrade direto para o plugin oficial do Claude Code para Telegram. Instale uma vez, ganhe 15+ recursos que o plugin oficial não tem. Construído sobre o plugin oficial — tudo funciona, só que melhor.

2 minutos para instalar. Zero configuração. Seu bot e pareamento existentes continuam funcionando.

Instale em uma linha

Instale o plugin oficial primeiro (no Claude Code: /plugin install telegram@claude-plugins-official), depois:

curl -fsSL https://raw.githubusercontent.com/k1p1l0/claude-telegram-supercharged/master/install.sh | bash

Execute novamente a qualquer momento para atualizar. O passo a passo completo está em Começando.

Segurança: a única fonte oficial é github.com/k1p1l0/claude-telegram-supercharged. Este projeto nunca distribui downloads em zip ou exe. Cópias em outros lugares que oferecem um arquivo zip são malware; por favor, não as execute e denuncie ao GitHub.

Oficial vs Supercharged

	Plugin oficial	Supercharged
Texto, fotos, arquivos, figurinhas	✅	✅
Respostas formatadas, divisão de mensagens longas	✅	✅
Mensagens de voz	Arquivo de áudio bruto	✅ Transcritas (OpenAI, Groq, Deepgram ou Whisper local)
Respostas de voz	❌	✅ ElevenLabs
Progresso ao vivo enquanto o Claude trabalha	❌	✅ Modo Agêntico
Histórico e memória que sobrevivem a reinicializações	❌	✅ SQLite + arquivo de memória
Sabe a qual mensagem você respondeu	❌	✅ Contexto de resposta, citações, encaminhamentos
Perguntas com botões inline	❌	✅ `ask_user`
Mensagens agendadas e lembretes	❌	✅ Também sincroniza com o Apple Reminders
Google Calendar	❌	✅
Daemon 24/7 com reinício automático	❌	✅ Supervisor launchd
Roteamento de modelos (Haiku / Sonnet / Opus)	❌	✅
Respostas longas como artigos Telegraph	❌	✅
Aprovar solicitações de permissão pelo Telegram	✅	✅ Botões ou "sim ", além de uma lista de aprovação automática

Recursos

Voz e Áudio

Recurso	O que faz
🎤 Mensagens de Voz	Fale com o Claude. Cadeia de fallback de provedores: OpenAI Whisper → Groq → Deepgram → whisper-cli local. Funciona do seu celular enquanto caminha.
🔊 Respostas de Voz (TTS)	O Claude responde com mensagens de voz via ElevenLabs TTS. Formato nativo OGG/Opus. Fallback automático para arquivo de áudio se a voz estiver restrita.
🎤 Transcrição Automática	TODAS as mensagens de voz em chats em grupo são transcritas, mesmo sem mencionar o bot. Configurável via `autoTranscribe`.

Mensagens e Mídia

Recurso	O que faz
📨 Mensagens Encaminhadas	Contexto completo de encaminhamento preservado — o Claude vê quem enviou originalmente e de qual chat/canal.
📦 Agrupamento de Mensagens	Encaminhe 20+ mensagens de uma vez — coletadas em um lote (debounce de 5s), resumidas automaticamente na hora, e o Claude responde a conversa inteira em uma única resposta.
📄 Suporte a Documentos	Envie PDFs, DOCX, CSV, TXT, JSON — o Claude baixa, lê e resume. Limite de 10MB por arquivo.
🎨 Escape Automático MarkdownV2	Caracteres especiais escapados automaticamente no servidor — o Claude escreve texto natural, sem necessidade de escape manual de `\.`.
😎 Suporte a Figurinhas e GIFs	O Claude vê figurinhas e GIFs. Estáticos como imagens, animados como colagens de múltiplos quadros.
📰 Telegraph Instant View	Pesquisas longas (3000+ caracteres) publicadas em telegra.ph como Instant View. Desativado por padrão — opt-in via `TELEGRAPH_ENABLED=true`.

Conversas e Grupos

Recurso	O que faz
💬 Histórico de Mensagens	Armazenamento contínuo baseado em SQLite. O Claude tem contexto entre reinicializações. Ferramentas `get_history` + `search_messages`.
🧠 Memória de Conversa	`/clean` salva um resumo antes de limpar. A memória persiste entre sessões. O Claude nunca esquece.
🧵 Encadeamento de Conversas	Segue cadeias de resposta em grupos, vê quem disse o quê, responde no tópico correto. Até 3 níveis de profundidade.
📋 Tópicos de Fórum	Tópicos de Fórum do Telegram totalmente suportados. Cada tópico isolado com `thread_id` persistente.
👥 Pareamento em Grupo	Adicione o bot ao grupo, mencione-o, receba o código de pareamento. Sem procurar IDs numéricos de chat.
🎯 Botões Inline	Ferramenta `ask_user` — botões tocáveis para confirmações e escolhas.
👍 Status por Reação	👀 lido → 🔥 trabalhando → 👍 concluído. Mensagens de voz recebem ✍ para transcrição.

Daemon e Infraestrutura

Recurso	O que faz
⚡ Roteamento de Modelos em Dois Níveis	Roteador configurável: Haiku (rápido, 200K), Sonnet (equilibrado, 1M) ou Opus (profundo, 1M). Defina via `TELEGRAM_ROUTER_MODEL`. Tarefas complexas escalam automaticamente para Opus via subagentes (altere o alvo com `TELEGRAM_ESCALATION_MODEL`).
🛠 Modo Agêntico	Veja o Claude trabalhar: "digitando…" o tempo todo, além de uma mensagem ao vivo "Trabalhando… (Ns)" com as anotações do Claude e cada chamada de ferramenta em execução. A resposta substitui no lugar. `/verbose 0\|1\|2`, `/status`, `/new`. Detalhes
🔄 Modo Daemon	O supervisor reinicia o Claude automaticamente em caso de falha ou redefinição de contexto. Memória preservada, zero tempo de inatividade.
🛡 Vigia de Contexto	Reinício automático quando o contexto excede 50%, ou após 2 horas de atividade, para manter as sessões responsivas. Histórico SQLite e memória sobrevivem a reinicializações.
🔒 Bloqueio de Instância Única	Arquivo de bloqueio baseado em PID impede instâncias duplicadas do bot competindo por atualizações do Telegram.
🖥 Gerenciamento do Daemon	`/telegram:daemon start\|stop\|restart\|status\|logs` — ciclo de vida completo. `/telegram:monitor` para painel de saúde com URL de controle remoto.
⏰ Mensagens Agendadas	Ferramenta `schedule` para lembretes e tarefas recorrentes. Tipos "at" (única vez) e "every" (intervalo). Persiste entre reinicializações.
📅 Google Calendar	Verifique a agenda, crie eventos, resumos diários pelo Telegram. Suporte a múltiplas contas. Proativo — o Claude usa o contexto do calendário ao responder.
📸 Capturas de Tela Headless	Captura de página baseada em Playwright — funciona em modo daemon onde o Chrome não está disponível.
✅ Validação por Reação	Lista branca de emojis no lado do cliente evita erros crípticos da API do Telegram.
🔒 Proteção contra Injeção de Shell	Todas as chamadas de subprocesso usam `spawnSync` com argumentos em array. Sem interpretação de shell.
📊 Cache Inteligente	Voz/áudio em cache entre middleware e handlers. Sem downloads ou transcrições duplicadas.

Começando

Fluxo de pareamento padrão para bot DM de usuário único. Veja ACCESS.md para grupos e configurações multiusuário.

Pré-requisitos

Bun — o servidor MCP roda no Bun. Instale com curl -fsSL https://bun.sh/install | bash.

1. Crie um bot com o BotFather

Abra um chat com @BotFather no Telegram e envie /newbot. O BotFather pede duas coisas:

Nome — o nome de exibição mostrado nos cabeçalhos do chat (qualquer coisa, pode conter espaços)
Nome de usuário — um identificador único terminando em bot (ex.: my_assistant_bot). Isso se torna o link do seu bot: t.me/my_assistant_bot.

O BotFather responde com um token que parece 123456789:AAHfiqksKZ8... — esse é o token completo, copie incluindo o número inicial e os dois pontos.

2. Instale o plugin oficial

Estes são comandos do Claude Code — execute claude para iniciar uma sessão primeiro.

/plugin install telegram@claude-plugins-official

3. Aplique a versão supercharged

Clone este repositório e instale tanto o servidor supercharged quanto o supervisor do daemon:

git clone https://github.com/k1p1l0/claude-telegram-supercharged.git
cp claude-telegram-supercharged/server.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)/server.ts
mkdir -p ~/.claude/scripts
cp claude-telegram-supercharged/supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
cp claude-telegram-supercharged/scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
chmod +x ~/.claude/scripts/claude-daemon-wrapper.exp
cp claude-telegram-supercharged/scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.ts

4. Dê o token ao servidor

/telegram:configure 123456789:AAHfiqksKZ8...

Grava TELEGRAM_BOT_TOKEN=... em ~/.claude/channels/telegram/.env. Você também pode escrever esse arquivo manualmente, ou definir a variável no seu ambiente de shell — o shell tem precedência.

5. Relance com a flag de canal

O servidor não conecta sem isso — saia da sua sessão e inicie uma nova:

claude --channels plugin:telegram@claude-plugins-official

Ou use o supervisor do daemon para operação sempre ativa com reinício automático e redefinição de contexto pelo Telegram (veja Modo Daemon):

bun ~/.claude/scripts/telegram-supervisor.ts

6. Pareie

Com o Claude Code em execução da etapa anterior, envie DM ao seu bot no Telegram — ele responde com um código de pareamento de 6 caracteres. Se o bot não responder, certifique-se de que sua sessão está rodando com --channels. Na sua sessão do Claude Code:

/telegram:access pair <code>

Seu próximo DM chega ao assistente.

Diferente do Discord, não há etapa de convite de servidor — bots do Telegram aceitam DMs imediatamente. O pareamento cuida da busca do ID de usuário para que você nunca precise lidar com IDs numéricos.

7. Proteja

O pareamento serve para capturar IDs. Depois que você estiver dentro, mude para allowlist para que estranhos não recebam respostas com código de pareamento. Peça ao Claude para fazer isso, ou /telegram:access policy allowlist diretamente.

Atualizando

Importante: O plugin oficial atualiza automaticamente e sobrescreverá seu server.ts supercharged. Quando o bot parar de funcionar de repente após uma atualização, é por isso.

A maneira mais rápida de atualizar (também após uma atualização do plugin oficial) é executar novamente o instalador de uma linha. Para fazer manualmente:

Quando o plugin oficial atualizar (verifique novos diretórios de versão em ~/.claude/plugins/cache/claude-plugins-official/telegram/):

cd claude-telegram-supercharged
git pull
# Find the current version (e.g. 0.0.4)
PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)
echo "Updating to version: $PLUGIN_VERSION"
cp server.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/server.ts
cp supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
# Copy skills
cp -r skills/* ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/skills/
# Copy scripts
cp scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
cp scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.ts

Depois reinicie seu daemon ou sessão do Claude Code.

Ferramentas Expostas ao Assistente

Ferramenta	Finalidade
`reply`	Enviar para um chat. Recebe `chat_id` + `text`, opcionalmente `reply_to` (ID da mensagem) para encadeamento nativo, `files` (caminhos absolutos) para anexos e `parse_mode` (MarkdownV2/HTML/texto simples, padrão MarkdownV2). Imagens (`.jpg`/`.png`/`.gif`/`.webp`) são enviadas como fotos com pré-visualização inline; outros tipos são enviados como documentos. Máximo de 50MB cada. Divide texto automaticamente em partes; arquivos são enviados como mensagens separadas após o texto. Retorna o(s) ID(s) da(s) mensagem(ns) enviada(s).
`react`	Adiciona uma reação de emoji a uma mensagem por ID. Apenas a lista fixa do Telegram é aceita (👍 👎 ❤ 🔥 👀 🎉 😂 🤔 etc). Também usada para indicadores de status (👀 lido → 👍 concluído).
`edit_message`	Edita uma mensagem que o bot enviou anteriormente. Suporta `parse_mode` (MarkdownV2/HTML/texto simples). Útil para atualizações de progresso "trabalhando..." → resultado. Funciona apenas nas próprias mensagens do bot.
`ask_user`	Envia uma pergunta com botões de teclado inline e aguarda a escolha do usuário. Recebe `chat_id`, `text`, `buttons` (matriz de rótulos), opcionalmente `parse_mode` e `timeout` (padrão 120s). Retorna o rótulo do botão pressionado.
`get_history`	Recupera o histórico recente de mensagens de um chat. Recebe `chat_id`, opcionalmente `limit` (padrão 50, máximo 200), opcionalmente `before` (timestamp unix para paginação). Retorna mensagens formatadas com carimbos de data/hora, remetentes e conteúdo.
`search_messages`	Pesquisa o histórico de mensagens por padrão de texto. Recebe `chat_id`, `query` (correspondência de substring), opcionalmente `limit` (padrão 20, máximo 100). Retorna mensagens correspondentes.
`clear_history`	Limpa todo o histórico de mensagens de um chat. Sempre confirme com `ask_user` primeiro e chame `save_memory` antes de limpar para preservar o contexto. Passe `restart_context: true` para sinalizar ao daemon supervisor reiniciar o Claude para um reset completo de contexto.
`save_memory`	Salva um resumo da conversa na memória persistente. Carregado nas instruções do Claude a cada inicialização. Use antes de `clear_history` para que o contexto sobreviva entre sessões.
`create_telegraph_page`	Publica conteúdo de formato longo no Telegraph (telegra.ph) e retorna uma URL. O Telegram o renderiza como Instant View — um leitor de artigos nativo. Recebe `title`, `content` (Markdown), opcionalmente `author_name` e `author_url`. Cria automaticamente uma conta Telegraph no primeiro uso.

Eventos de Entrada

Evento	Descrição
Mensagem de texto	Encaminhada ao Claude como notificação de canal com `chat_id`, `message_id`, `user`, `ts`.
Foto	Baixada para a caixa de entrada, caminho incluído na notificação para que o Claude possa `Read`.
Reação de emoji	Quando um usuário reage a uma mensagem do bot, o Claude recebe uma notificação com `event_type: "reaction"`, o emoji e o `message_id`. Use como feedback leve.
Mensagem de voz	Baixada para a caixa de entrada como `.ogg`, transcrita automaticamente pelo servidor se o whisper estiver instalado. A transcrição substitui "(mensagem de voz)" no texto da notificação. O caminho do áudio ainda é incluído como `audio_path`.
Arquivo de áudio	Arquivos de áudio encaminhados (`.mp3`, etc.) baixados para a caixa de entrada, caminho incluído como `audio_path`.
Sticker	`.webp` estático passado diretamente como `image_path`. Stickers animados (`.tgs`) e de vídeo (`.webm`) convertidos em colagem de múltiplos quadros. Emoji e nome do pacote incluídos no texto.
GIF / Animação	Baixado e convertido em uma colagem horizontal de múltiplos quadros para que o Claude possa ver o conteúdo da animação.

Mensagens de entrada acionam automaticamente um indicador de digitação — o Telegram mostra "botname está digitando..." enquanto o assistente trabalha em uma resposta.

Mensagens de Voz e Áudio

Mensagens de voz e arquivos de áudio são baixados para ~/.claude/channels/telegram/inbox/ e transcritos automaticamente pelo servidor. O texto da transcrição substitui "(mensagem de voz)" na notificação, então o Claude recebe o texto falado diretamente.

Pense nisso como Wispr Flow para Claude Code. Abra o Telegram, segure o botão do microfone, diga "refatore o middleware de autenticação para usar JWT" — o Claude recebe isso como texto e começa a trabalhar. Sem digitação, sem necessidade de aplicativo de desktop, funciona do seu celular.

Configuração de Transcrição

O servidor tenta métodos de transcrição nesta ordem:

OpenAI Whisper API (recomendado) — mais rápido, maior qualidade, não bloqueante. Defina sua chave de API em ~/.claude/channels/telegram/.env:
```
OPENAI_API_KEY=sk-proj-...
```
Usa whisper-1 por padrão ($0,006/min). Você pode mudar para um modelo diferente:
```
OPENAI_WHISPER_MODEL=gpt-4o-transcribe
```
Sem necessidade de instalação local. O método de transcrição ativo é registrado na inicialização.

whisper.cpp (fallback local) — brew install whisper-cpp. Porte rápido em C++, funciona totalmente offline. Requer um arquivo de modelo:

# Download the small multilingual model (465MB, good quality/speed balance)
mkdir -p /usr/local/share/whisper-cpp/models
curl -L -o /usr/local/share/whisper-cpp/models/ggml-small.bin \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"

openai-whisper (fallback local) — pip install openai-whisper. Baseado em Python, mais lento mas também funciona offline.
Sem transcrição — mensagens de voz ainda são baixadas e o audio_path é incluído na notificação, mas nenhuma transcrição é fornecida.

Opções locais (2 e 3) requerem ffmpeg (brew install ffmpeg) para conversão de formato de áudio. Se você tiver uma chave de API OpenAI, a opção 1 é recomendada — é assíncrona (não bloqueia o loop de eventos), mais rápida e mais precisa.

Transcrição automática no histórico

Quando autoTranscribe está habilitado (o padrão), o servidor transcreve todas as mensagens de voz/áudio em chats de grupo — até mesmo aquelas que não mencionam o bot. Isso significa que get_history e o contexto injetado automaticamente sempre mostram o texto falado (prefixado com 🎤) em vez de [voice]. O Claude recebe contexto conversacional completo, incluindo o que as pessoas disseram em mensagens de voz.

Para desabilitar (por exemplo, para economizar CPU em grupos movimentados):

/telegram:access set autoTranscribe false

Para reabilitar:

/telegram:access set autoTranscribe true

Telegraph (Artigos Instant View)

O Claude pode publicar conteúdo de formato longo no Telegraph e enviá-lo como links Instant View no Telegram — um leitor de artigos nativo em tela cheia. O Telegraph está desabilitado por padrão porque as postagens são publicamente acessíveis por URL.

Para habilitar, adicione a ~/.claude/channels/telegram/.env:

TELEGRAPH_ENABLED=true

Quando habilitado, o Claude só usa o Telegraph para conteúdo realmente longo (3000+ caracteres com múltiplas seções) — relatórios de pesquisa, análises abrangentes, guias detalhados. Respostas regulares sempre permanecem no chat.

Quando desabilitado (padrão):

A ferramenta create_telegraph_page fica oculta do Claude
O Claude envia todo o conteúdo diretamente em mensagens de chat
O prompt do sistema não menciona o Telegraph

Requer reinicialização do servidor MCP para ter efeito.

Memória de Conversa

Quando você limpa o histórico do chat, o Claude primeiro salva um resumo curto em ~/.claude/channels/telegram/data/memory.md. Este arquivo é carregado nas instruções do Claude a cada inicialização — então o contexto de sessões anteriores nunca é totalmente perdido.

Resumos são datados e marcados com o ID do chat
O arquivo se comprime automaticamente quando excede 10.000 caracteres (a metade mais antiga é cortada)
Funciona entre /clear e reinicializações do Claude Code

Modo Daemon

O plugin inclui um script supervisor (supervisor.ts) que executa o Claude Code como um processo filho gerenciado. Ele lida com:

Reinício automático em caso de falha — backoff exponencial (1s, 2s, 4s... até 30s), reinicia após 60s de uptime estável
Reset de contexto pelo Telegram — diga "limpar tudo" no Telegram, o Claude salva a memória, limpa o histórico e o supervisor reinicia o Claude com uma sessão nova. Zero tempo de inatividade, memória preservada.
Protocolo de arquivo de sinal — o servidor MCP escreve ~/.claude/channels/telegram/data/restart.signal, o supervisor o detecta em 500ms, espera 3 segundos para o Claude terminar de enviar respostas, então mata e recria o processo

Uso

Se você seguiu os passos de Introdução, o supervisor já está instalado em ~/.claude/scripts/telegram-supervisor.ts. Basta executar:

bun ~/.claude/scripts/telegram-supervisor.ts

Flags extras são encaminhadas ao Claude:

bun supervisor.ts --effort high

O supervisor inicia o Claude com --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions por padrão.

Modo Agente

No modo daemon, você pode assistir o Claude trabalhar, como faria no terminal:

You: Read the README and check package.json for the scripts
Bot: Working... (14s)
     💬 Reading the README to see the install steps.
     💻 Bash: Read README intro
     💬 Now checking package.json for the scripts.
     📖 Read: package.json
     ✍️ Writing…
Bot: [the answer replaces the Working message]

Indicador de digitação durante todo o tempo em que o Claude trabalha, em todos os níveis de verbosidade. Ele pausa enquanto uma pergunta de ask_user aguarda sua resposta.
Mensagem de trabalho quando uma execução dura mais de 2,5 segundos, então respostas rápidas nunca recebem uma. Ela mostra as notas curtas do Claude (💬), cada chamada de ferramenta conforme inicia (Read, Edit, Bash, Grep, WebFetch, Agent, Skill, ferramentas MCP e assim por diante), e o que o Claude está fazendo no momento: 💭 Thinking… após uma ferramenta retornar, ✍️ Writing… quando está produzindo saída.
A resposta substitui a mensagem de trabalho no lugar. O Telegram não envia notificação push para edições, então essas respostas chegam silenciosamente. Respostas rápidas, respostas em várias partes, arquivos e respostas com citação chegam como mensagens normais.
A mensagem de trabalho é sempre a mais recente. Se você escrever enquanto o Claude trabalha, ela se move para baixo da sua mensagem. As ferramentas próprias do Telegram (responder, reagir e assim por diante) e ToolSearch não são listadas.
Apenas mensagens diretas, porque linhas de ferramentas podem mostrar caminhos de arquivos e comandos.

Comando	O que faz
`/verbose 0`	Sem mensagem de trabalho: apenas indicador de digitação e a resposta
`/verbose 1`	Notas e nomes de ferramentas com um alvo curto (padrão)
`/verbose 2`	Notas mais longas e entradas completas de ferramentas (comandos, caminhos, URLs)
`/status`	Trabalhando ou ocioso, tempo decorrido, contagem de ferramentas, uptime, modelo do roteador
`/new`	Nova sessão do Claude através do supervisor. Memória e histórico são mantidos.

Comandos respondem a usuários na lista de permissões em mensagens diretas. /verbose é armazenado por chat.

Como funciona. O supervisor passa scripts/telegram-progress-hook.ts ao Claude como um hook de PreToolUse, PostToolUse e Stop via --settings, então nunca é executado em suas sessões interativas. O hook anexa cada evento a ~/.claude/channels/telegram/data/progress.jsonl, e o servidor monitora esse arquivo e edita a mensagem de trabalho (no máximo uma edição a cada 1,5 segundos). As notas do Claude e a fase de pensamento/escrita vêm da transcrição da sessão. As instruções do servidor pedem ao Claude para escrever uma frase curta antes de cada chamada de ferramenta.

Configuração (ambiente do supervisor): TELEGRAM_VERBOSE define o nível padrão (1). TELEGRAM_AGENTIC_MODE=off desativa o hook.

Como funciona o reset de contexto

O usuário envia "limpar tudo" no Telegram
O Claude confirma via botões inline (ask_user)
O Claude salva um resumo da conversa (save_memory)
O Claude envia uma resposta de confirmação ao Telegram
O Claude chama clear_history com restart_context: true
O servidor MCP escreve restart.signal com um atraso de 3 segundos
O supervisor detecta o arquivo, espera o Claude terminar e então mata o processo
O supervisor inicia uma nova sessão do Claude — memory.md é carregado nas instruções automaticamente

Sempre ativo com launchd (macOS)

Executar o supervisor em um terminal (ou tmux/screen) funciona para sessões rápidas, mas tem um problema fundamental no macOS: o sistema suspende processos em segundo plano agressivamente. Quando você fecha a tampa, troca de usuário ou o Mac entra em repouso, o macOS envia SIGSTOP para processos de terminal — seu bot fica silencioso até você abrir a tampa novamente. tmux/screen não ajudam porque rodam no espaço do usuário e também são suspensos.

launchd é o gerenciador de processos nativo da Apple — o mesmo sistema que mantém Spotlight, Time Machine e iCloud funcionando. Ele opera no nível do sistema operacional, fora de qualquer sessão de terminal, então:

Sobrevive ao fechamento da tampa — o processo continua rodando quando você fecha seu MacBook (na energia)
Sobrevive ao logout — permanece ativo mesmo se você sair da sua sessão de usuário
Inicia automaticamente na inicialização — sem necessidade de lembrar de iniciá-lo após um reinício
Reinicia automaticamente em caso de falha — se o supervisor morrer inesperadamente, o launchd o traz de volta
Permanece acordado — envolvemos o supervisor com caffeinate -s para evitar o repouso do sistema

Configuração

Crie ~/Library/LaunchAgents/com.user.claude-telegram.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.claude-telegram</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/caffeinate</string>
        <string>-s</string>
        <string>/path/to/bun</string>
        <string>/Users/YOU/.claude/scripts/telegram-supervisor.ts</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/YOU/.claude/channels/telegram/data/supervisor-stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/YOU/.claude/channels/telegram/data/supervisor-stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/path/to/bun/dir:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>

    <key>WorkingDirectory</key>
    <string>/Users/YOU</string>

    <key>ProcessType</key>
    <string>Background</string>

    <key>ThrottleInterval</key>
    <integer>10</integer>
</dict>
</plist>

Substitua /path/to/bun pelo seu caminho do bun (which bun) e /Users/YOU pelo seu diretório inicial.

Não sobrescreva HOME no plist. O wrapper executa o claude a partir de ~/.claude-telegram-daemon, porque um cwd de $HOME faz o Claude Code descartar o plugin do telegram. Para usar outro diretório, defina TELEGRAM_DAEMON_CWD em EnvironmentVariables. Se o daemon se comportar mal, consulte Solução de problemas do daemon.

Importante: Tanto RunAtLoad quanto KeepAlive devem ser definidos como <true/> para operação sem intervenção. RunAtLoad inicia o daemon automaticamente no login/inicialização. KeepAlive instrui o launchd a reiniciar o processo se ele sair inesperadamente. Definir qualquer um como <false/> significa que você precisará iniciar o daemon manualmente ou ele não se recuperará de falhas.

Gerenciando o daemon

Iniciar o daemon:

launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist

Parar o daemon:

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist

Verificar se está em execução:

launchctl list | grep claude-telegram

Um daemon em execução mostra seu PID na primeira coluna. Um 0 na coluna de status significa que ele saiu limpo; não zero significa que ele travou (o launchd o reiniciará).

Ver logs:

tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log

Reiniciar (recarregar configuração após editar o plist):

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist

Remover completamente (parar + excluir):

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
rm ~/Library/LaunchAgents/com.user.claude-telegram.plist

Monitorando o daemon

Use a skill de monitoramento integrada de qualquer sessão do Claude Code:

/telegram:monitor

Mostra um painel ao vivo: status do processo para todos os componentes, estado do launchd, logs recentes, saúde do MCP, URL de controle remoto (assista ao daemon ao vivo no seu navegador) e status do arquivo de bloqueio.

Você também pode monitorar manualmente:

# Live supervisor logs
tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log

# Quick alive check
ps aux | grep "channels.*telegram" | grep -v grep && echo "ALIVE" || echo "DEAD"

# Find the remote control URL (open in browser to watch the daemon live)
strings ~/.claude/channels/telegram/data/supervisor-stdout.log | grep "session_" | tail -1

Como as camadas funcionam juntas

launchd (OS-level)
  └── caffeinate -s (prevents system sleep)
        └── supervisor.ts (manages Claude lifecycle)
              └── claude --channels plugin:telegram (the actual bot)

launchd garante que a árvore de processos esteja sempre ativa
caffeinate mantém o Mac acordado enquanto o processo está em execução
supervisor lida com reinicializações específicas do Claude (reset de contexto, recuperação de falhas com backoff)
Claude executa como um processo filho gerenciado com o canal do Telegram

Nota: caffeinate -s evita o sono apenas quando conectado à energia. Na bateria com a tampa fechada, o macOS eventualmente dormirá independentemente. Para disponibilidade real 24/7 na bateria, considere executar em um servidor.

Grupos e Encadeamento de Conversas

O plugin suporta grupos com encadeamento inteligente de conversas — o Claude pode seguir cadeias de respostas, ver quem disse o quê e responder no tópico correto.

Configuração

1. Desative o modo de privacidade no BotFather

Por padrão, os bots do Telegram em grupos só veem comandos e mensagens que os mencionam. Para rastreamento completo de tópicos, desative o modo de privacidade:

Abra @BotFather no Telegram
Envie /mybots → selecione seu bot
Bot Settings → Group Privacy → Turn off

Se você preferir manter o modo de privacidade ativado, o bot ainda funcionará — ele só não verá mensagens que não o mencionam, então o rastreamento de tópicos será incompleto.

2. Adicione o bot a um grupo

Adicione seu bot a qualquer grupo do Telegram como um membro normal.

3. Vincule o grupo (automático)

Basta enviar uma mensagem no grupo mencionando seu bot (ex.: @your_bot hello). O bot responde com um código de vinculação de 6 caracteres — mesmo fluxo da vinculação por DM:

/telegram:access pair <code>

É isso. O grupo é registrado automaticamente com requireMention: true (o bot só responde quando mencionado ou respondido).

Para permitir que ele responda a todas as mensagens:

/telegram:access group update -100XXXXXXXXXX requireMention false

Alternativa manual: Se você já sabe o ID numérico do grupo (começa com -100...), pode registrar diretamente com /telegram:access group add -100XXXXXXXXXX. Maneiras de encontrar o ID: verifique os logs de stderr do bot, abra web.telegram.org (o ID está na URL) ou encaminhe uma mensagem do grupo para @RawDataBot.

4. Reinicie o Claude Code

claude --channels plugin:telegram@claude-plugins-official

Como o Encadeamento Funciona

Quando alguém responde a uma mensagem no grupo, o Claude recebe reply_to_text e reply_to_user mostrando o que foi respondido
O plugin rastreia até 200 mensagens por chat (TTL de 4 horas) e percorre cadeias de respostas até 3 níveis de profundidade, fornecendo thread_context na notificação
As mensagens enviadas pelo próprio Claude também são rastreadas, então as cadeias de respostas funcionam de ponta a ponta
O Claude automaticamente encadeia suas respostas à mensagem que as acionou

Tópicos do Fórum

Se o seu supergrupo tem Topics habilitado, o plugin encaminha thread_id (o message_thread_id do Telegram) e o repassa nas respostas — mantendo as conversas no tópico correto do Fórum automaticamente. Os IDs dos tópicos são persistidos no SQLite para que o contexto seja preservado entre reinicializações.

Controle de Acesso

Documentação completa de controle de acesso em ACCESS.md — políticas de DM, grupos, detecção de menção, configuração de entrega, comandos de skill e o esquema access.json.

Referência rápida: A política padrão é pairing — DMs e grupos usam o fluxo de vinculação. Para DMs, envie uma mensagem ao bot para obter um código. Para grupos, adicione o bot e mencione-o para obter um código. Então /telegram:access pair <code> aprova qualquer um. ackReaction só aceita a lista fixa de emojis do Telegram.

Aprovações de Permissão

Se sua sessão não pular permissões, o Claude Code envia cada solicitação de aprovação para o Telegram. Cada DM na lista de permitidos recebe uma mensagem como 🔐 Permission: Bash com botões See more, ✅ Allow e ❌ Deny. Você também pode responder yes <id> ou no <id> com o ID de cinco letras da mensagem. Apenas usuários na lista de permitidos podem responder, e uma solicitação pode ser respondida uma vez; cada cópia do prompt então mostra o resultado. Membros do grupo não podem aprovar.

Para pular a ida e volta para ferramentas que você sempre permite, liste-as em access.json:

{ "autoApproveTools": ["Read", "Grep", "Glob"] }

O daemon executa com --dangerously-skip-permissions, então nunca pergunta. Isso é para sessões que você inicia sem essa flag.

Reações de Confirmação

O bot pode reagir a mensagens recebidas com um emoji para sinalizar que recebeu e está processando. Isso é controlado pelo campo ackReaction em access.json:

{
  "ackReaction": "👀"
}

Fluxo de reação:

Estágio	Emoji	Quando
Recebido	`👀` (configurável via `ackReaction`)	Imediatamente no recebimento
Processando voz	`✍`	Ao transcrever uma mensagem de voz
Trabalhando	`🔥`	Durante tarefas longas (múltiplas chamadas de ferramenta, pesquisa, geração de código)
Concluído	`👍`	Após o envio da resposta

O Telegram mantém apenas uma reação de bot por mensagem, então cada nova reação substitui a anterior — criando uma progressão natural de status.

Nota: ackReaction não está definido por padrão. Para habilitá-lo, adicione-o ao seu ~/.claude/channels/telegram/access.json. Ele só aceita emojis da lista fixa de reações do Telegram. Escolhas comuns: 👀, ⚡, 🔥.

Buffer de Histórico de Mensagens

Cada mensagem que passa pelo bot é capturada em um banco de dados SQLite local e persistida entre reinicializações. O Claude obtém contexto sem pedir que os usuários se repitam.

~/.claude/channels/telegram/data/messages.db

Como funciona:

Um middleware do grammY intercepta TODAS as mensagens (incluindo mensagens de grupo sem menção @bot) antes da verificação de acesso
Tanto mensagens recebidas quanto respostas do bot são armazenadas com deduplicação INSERT OR REPLACE
As últimas 5 mensagens são injetadas automaticamente em cada notificação para que o Claude sempre tenha contexto contínuo
get_history recupera até 200 mensagens com paginação; search_messages faz busca por substring
O modo WAL do SQLite garante gravações à prova de falhas — se o Claude Code travar, o banco de dados se recupera automaticamente na próxima inicialização
O buffer contínuo é podado automaticamente: limite de 500 mensagens/chat, TTL de 14 dias, limite rígido de 50MB

Limitações

A API de Bot do Telegram não expõe endpoint nativo de histórico — bots só veem mensagens em tempo real. Resolvemos isso com um armazenamento local de mensagens em SQLite (veja Histórico de Mensagens abaixo). Cada mensagem que passa pelo bot é capturada e persistida, dando ao Claude contexto completo entre reinicializações via ferramentas get_history e search_messages. O histórico está disponível desde quando o bot entrou no chat.

Fotos e mensagens de voz são baixadas imediatamente na chegada — não há como buscar anexos de mensagens históricas via API de Bot.

Roadmap

Concluído

Planejado

Mensagens agendadas — Enviar mensagens em um horário específico
Suporte a múltiplos bots — Executar vários bots a partir de uma instância de servidor
Limitação de taxa e estatísticas de uso — Rastrear uso de tokens e definir limites por usuário
Modo webhook — Alternativa ao polling para implantações de produção
Comandos personalizados — Definir comandos de bot que mapeiam para skills do Claude Code

Contribuindo

Este é um projeto comunitário. Queremos sua ajuda!

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/your-feature)
Faça suas alterações
Teste com um bot real do Telegram
Abra um PR com uma descrição clara do que você mudou e por quê

Diretrizes

Mantenha as alterações focadas — uma funcionalidade por PR
Teste com interações reais do Telegram, não apenas testes unitários
Atualize o README se você adicionar novos recursos ou ferramentas
Siga o estilo de código existente (TypeScript, biblioteca grammy)

Créditos

Plugin original por Anthropic (fonte) — licenciado sob Apache 2.0
Supercharged por @k1p1l0 e colaboradores
Inspirado no lançamento do Claude Code Channels por @boris_cherny

Licença

Apache 2.0 — Igual ao original. Veja LICENSE.