Como construir o teu assistente pessoal IA passo a passo com Claude Code, MCP e um bot de Telegram (tutorial 2026)

Pela equipa da Kiwop · Agência Digital especializada em Desenvolvimento de Software e Inteligência Artificial aplicada para clientes globais na Europa e EUA · Publicado a 19 de abril de 2026 · Última atualização: 19 de abril de 2026

TL;DR — Tutorial passo a passo para montar o teu assistente pessoal IA sobre Claude Code MCP como stack base: quatro canais (IMAP, Gmail, Slack, Telegram), briefings automáticos às 08:00 e 19:00, bot bidirecional e comandos slash. Cerca de 500 linhas de Python, zero dependências pagas para além da subscrição Claude Max x20. Setup completo em 60-90 minutos seguindo os passos.

Este é o segundo artigo da série sobre o PA da Kiwop. O primeiro, De OpenClaw a PA com Claude Code e MCP, explica porque o construímos após a mudança de política da Anthropic a 4 de abril de 2026. Este tutorial mostra como o construímos, com o código real que temos em produção há duas semanas. No final, terás um assistente pessoal IA funcional na tua máquina, com a mesma arquitetura que usamos diariamente na agência. O repositório de referência está em https://github.com/purroy/majordomo.

Não é uma demo de brincar. Processa correio de produção, agenda real, mensagens de Telegram a partir do telemóvel e briefings que aterram às 08:00 e às 19:00 sem intervenção humana. A filosofia é minimalista de propósito: cada peça faz uma única coisa, a cola entre peças é Unix, e os segredos nunca tocam o disco em claro.

Que vais construir

No final do tutorial, o teu PA terá quatro canais operativos e uma arquitetura deliberadamente simples.

Os quatro canais ativos do PA são:

• Correio IMAP/SMTP próprio: para a caixa corporativa do teu domínio (mail.tuaempresa.com), lido com scripts Python sobre a biblioteca padrão do Python. Leitura, triagem, redação e envio com confirmação explícita.
• Google Workspace (Gmail + Calendar + Drive): através dos MCP servers oficiais — podes adicionar outros similares como Outlook/Microsoft 365 se a tua organização os usar.
• Slack: DMs e menções, via MCP server oficial do Slack para Claude.
• Telegram: um bot bidirecional que é ao mesmo tempo canal de saída (briefings) e de entrada (falas com o PA a partir do telemóvel).

O stack técnico são quatro camadas. Claude Code como motor conversacional. Conectores MCP para tudo o que tem um oficial (Google + Slack). Scripts Python próprios para os buracos que o MCP não cobre (IMAP e Telegram). E launchd (em macOS) ou systemd/Task Scheduler (em Linux/Windows) para o arranque e os disparadores programados.

O custo marginal real é zero sobre a subscrição Claude Max x20 que já pagas para desenvolvimento. As cerca de 500 linhas de Python são tuas — nenhuma dependência instalável, apenas biblioteca padrão. Não há backend, não há base de dados, não há Docker. Todo o estado persistente vive em ficheiros locais e no chaveiro do sistema operativo.

A alto nível, a arquitetura segue três princípios que convém explicitar antes de entrarmos no código. O primeiro é que o Claude Code é o motor mas não é o dono do estado: os teus prompts estão em ficheiros Markdown versionáveis no teu próprio repositório, os teus segredos estão no chaveiro do sistema, os teus briefings são ficheiros em disco. Se amanhã quisesses mudar de motor, só terias de substituir as chamadas a claude --print por outra CLI equivalente. O segundo é que o MCP faz o trabalho pesado quando existe um servidor oficial (Google, Slack) e escreves código apenas quando não existe (IMAP, Telegram). O terceiro é que a segurança vive em três camadas independentes — OAuth do MCP, Keychain do macOS e regra de confirmação em prompts — de modo que comprometer uma não compromete o sistema.

Pré-requisitos e custo real

Antes de começar, revê que tens o que é preciso. O tutorial assume macOS porque é o que usamos nós, mas há uma secção no final sobre como portá-lo para Linux ou Windows.

Requisitos de conta e subscrição:

• Claude Max x20 da Anthropic: a subscrição "for power users", cerca de 200 dólares por mês. Claude Code vem incluído e é o motor do PA.
• Conta de Google Workspace com permissões para autorizar Gmail, Calendar e Drive via OAuth.
• Workspace de Slack onde tenhas conta (não é preciso ser admin para o MCP de leitura dos teus próprios DMs e menções).
• Um domínio de correio sobre IMAP se a tua caixa principal não for Gmail (opcional — se todo o teu correio for Gmail, salta o Passo 3).
• Conta de Telegram (gratuita) para criar o bot via @BotFather.

Requisitos de sistema:

• macOS 14+ com Homebrew instalado (para o fluxo base do tutorial).
• Python 3.11+ (vem com macOS recente; se não, brew install [email protected]).
• Claude Code CLI instalado: npm i -g @anthropic-ai/claude-code ou via brew.
• Terminal com permissões de Full Disk Access se quiseres que o launchd possa correr os briefings sem pedir autorização repetida.

Custo mensal projetado, desagregação honesta:

O ponto chave: o custo marginal do PA é zero se já tiveres Claude Max. Se não a tiveres e só a comprasses para o PA, o cálculo muda — terias de avaliar se a poupança de tempo te compensa 200 dólares por mês. Para qualquer pessoa que já use Claude Code em desenvolvimento, a resposta costuma ser sim de forma trivial.

O tempo estimado para completar o tutorial do zero, contando com os OAuth e o debug inevitável, é de 60 a 90 minutos. Se só quiseres os três primeiros canais (sem Telegram nem briefings programados), desces para 30-40 minutos.

Passo 1: estrutura base do projeto

O PA vive num diretório próprio fora de qualquer outro projeto. A primeira decisão é onde o colocar. Nós usamos ~/Dev/PA por convenção — substitui-o se preferires outro caminho. O repositório completo de referência está em https://github.com/purroy/majordomo — usa-o se te perderes em algum passo.

O .gitignore deve excluir qualquer coisa com dados pessoais — briefings, rascunhos de correio, estado do bot:

Agora o ficheiro mais importante do repositório: CLAUDE.md. Define a persona do assistente, idioma por defeito, e a regra de confirmação que é o coração da segurança do PA.

A regra de confirmação é inegociável. Diferencia um PA que podes deixar nas mãos de um modelo de linguagem de um que te vai enviar um correio embaraçoso quando interpretar mal um "sim" de há dois turnos. Testámo-la durante todo o mês de março sem um único falso positivo.

Commit inicial:

Passo 2: ligar MCP servers

MCP ([Model Context Protocol](https://modelcontextprotocol.io/specification/2025-11-25)) é o padrão aberto que a Anthropic publicou no final de 2024 para que os modelos de linguagem se liguem a ferramentas externas de forma uniforme. Um MCP server é um processo que expõe um conjunto de funções (ler correios, pesquisar ficheiros, enviar mensagens) através de um protocolo comum; um MCP client (como o Claude Code) arranca-o e consome essas funções como se fossem ferramentas próprias. Se quiseres aprofundar porque é que o MCP é a peça que desbloqueia os agentes IA em 2026, temos uma análise mais ampla em WebMCP: o teu site preparado para agentes IA.

Para o PA ativamos quatro MCP servers oficiais, os quatro publicados pela Anthropic/Claude ou pelos próprios fornecedores:

• Gmail MCP: leitura, pesquisa e composição de correios.
• Google Calendar MCP: agenda, criação e modificação de eventos.
• Google Drive MCP: pesquisa e leitura de ficheiros.
• Slack MCP: leitura de DMs, canais e envio com confirmação.

A forma mais simples de os configurar é através da interface do Claude Code. A partir da raiz do projeto (~/Dev/PA), lança:

Dentro da sessão interativa do Claude Code, adiciona os MCP servers com o comando /mcp add para cada um. O comando vai lançar-te o fluxo OAuth correspondente no browser — autoriza com a conta que queres que o PA use, não necessariamente a tua conta pessoal principal.

Segurança do fluxo OAuth. Um aspeto chave: os MCP servers oficiais usam OAuth do browser, não credenciais em disco. O teu refresh_token é guardado pelo MCP server nos seus próprios armazéns cifrados, não pelo PA. Isso significa que se alguém roubar o teu .claude/ ou o teu repositório, não leva acesso ao teu Gmail — teria de comprometer além disso o armazém do MCP server e, em última instância, o teu Keychain macOS. A superfície de ataque fica limitada.

Uma vez autorizados os quatro, verifica que o Claude Code os deteta:

Devias ver as ferramentas disponíveis agrupadas por serviço: mcp__claude_ai_Gmail__search, mcp__claude_ai_Google_Calendar__list_events, etcetera. A nomenclatura segue o padrão mcp__<server>__<tool>.

Neste ponto já podes perguntar ao PA "o que tenho hoje no calendário?" ou "pesquisa no Drive o contrato com o cliente X" e funciona. O que falta são os dois canais que o MCP não cobre bem: o correio IMAP corporativo e o Telegram.

Passo 3: scripts Python para IMAP e Keychain

Se todo o teu correio está em Gmail, este passo é opcional. Se, como nós, a caixa principal corre sobre um servidor IMAP próprio (mail.kiwop.com no nosso caso), é preciso escrever a ponte.

A arquitetura dos scripts é deliberadamente pequena. Um módulo interno _mail.py com a lógica comum (ligação IMAP, parseamento, SMTP), e três comandos mínimos que o PA pode invocar:

• mail_fetch.py: lista UIDs recentes ou não lidos como JSON.
• mail_read.py: lê o corpo completo de um UID (sem o marcar como lido — usa BODY.PEEK).
• mail_send.py: envia um correio ou guarda-o como rascunho.

Regra de ouro sobre credenciais. Nunca guardes a password IMAP num ficheiro do repo nem numa variável de ambiente persistente tipo ~/.zshrc. O risco não é teórico: cada vez que partilhas um script, fazes um commit com .env trackeado ou instalas uma extensão de VS Code que lê o teu ambiente, estás a expor segredos. Em macOS temos Keychain, um chaveiro cifrado do sistema operativo acessível via o comando security. Os scripts leem a credencial ao voo quando precisam dela e nunca a escrevem em disco.

Primeiro, guarda as credenciais no Keychain:

Os portos habituais: 993 para IMAP sobre SSL e 587 para SMTP com STARTTLS. Se o teu fornecedor usar SMTPS implícito, muda para 465.

Agora o helper shell que lê e escreve no Keychain. Chamamos-lhe scripts/keychain.sh:

O equivalente Python usa subprocess para invocar security:

O fallback para variável de ambiente é deliberado: quando portares isto para Linux (systemd), aí o security não existe e usarás env vars exportadas a partir do unit file, lidas de um ficheiro com permissões 600.

Com o Keychain ligado, o mail_fetch.py fica claro. É um CLI que imprime JSON para que o Claude Code o parseie facilmente:

O mail_send.py acrescenta uma salvaguarda importante: sem a flag --yes, guarda a mensagem como .eml em drafts/ e não a envia. Apenas com --yes explícito sai por SMTP. Isto aplica a regra de confirmação do CLAUDE.md ao nível do código, não apenas do prompt — mesmo que o modelo saltasse a regra, o script não enviaria.

Detalhe crítico sobre `BODY.PEEK`. Quando o PA "lê" um correio para o triar, não o deve marcar como lido. Se o marcares, perdes a tua caixa de pendentes como sinal visual no cliente de correio. A flag IMAP que define \Seen é BODY[]; a que não a define é BODY.PEEK[]. Usa-a sempre em mail_read.py.

Passo 4: bot de Telegram com sessão persistente

O bot de Telegram é a peça mais interessante do PA porque inverte o fluxo: em vez de seres tu a abrir um terminal e a escrever para o Claude, o Claude recebe as tuas mensagens a partir do telemóvel.

O plano: um daemon Python que faz long polling contra a API do Telegram (sem necessidade de webhook público), e cada mensagem que recebe reencaminha-a para claude --print com uma sessão executada dentro do repositório do PA. O Claude executa o prompt com todas as suas ferramentas (MCP + scripts Python) e devolve a resposta. O daemon formata-a para Telegram e envia-a de volta para o chat.

Criar o bot leva dois minutos. Abre o Telegram, fala com o @BotFather, lança /newbot, dá-lhe um nome e um username. Devolve-te um token tipo 123456:ABC-XYZ_.... Guarda-o no Keychain e a seguir deteta o teu chat_id (o ID da conversa 1-a-1 entre tu e o bot):

Agora o daemon. O esqueleto de telegram_bot.py é este:

Três detalhes não óbvios do desenho.

Primeiro, whitelist de `chat_id`: a variável allowed_chat é o teu próprio chat e qualquer mensagem de outro chat_id é descartada silenciosamente. Se alguém descobrir o username do teu bot e lhe mandar mensagens, ele não responde. É a barreira mais simples mas mais eficaz contra o abuso.

Segundo, `--permission-mode bypassPermissions`: o daemon corre sem pedir confirmação para executar scripts do repo porque não há um humano à frente que possa responder. A segurança não vem dos prompts do Claude Code, vem de (a) o daemon só responder ao chat_id whitelisted, (b) o PA ter a regra de confirmação em CLAUDE.md, e (c) os scripts sensíveis como mail_send.py exigirem --yes ao nível do código.

Terceiro, sessões efémeras por mensagem. Cada ask_claude gera um session-id novo com uuid.uuid4(). Isso significa que o bot não mantém memória de conversa entre mensagens — cada pedido parte do zero com o teu CLAUDE.md e os teus comandos carregados. A memória "longa" (as tuas preferências, assinatura, contactos prioritários) vive em memory/ como ficheiros que o Claude lê ao iniciar cada sessão, não na própria sessão. Isto evita acumular contexto obsoleto e torna o comportamento muito previsível.

Markdown compatível com Telegram. O Telegram não renderiza Markdown estilo GitHub (não entende tabelas, não entende links com parênteses retos em muitos contextos, interpreta mal certos caracteres). Em vez de lutar com parse_mode: MarkdownV2 — que te obriga a escapar todos os caracteres especiais e parte com facilidade — usamos um pequeno conversor para texto simples legível (md_to_telegram.py) que elimina a sintaxe Markdown preservando a estrutura.

Para o testares antes do launchd:

Abre o Telegram, escreve /ping ao teu bot. Deve responder pong. Envia depois "que horas são?" — deve responder-te com a hora atual consultando o sistema via sessão do Claude. Parabéns: já tens um PA acessível a partir do telemóvel.

Passo 5: briefings programados com launchd

[`launchd`](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) é o gestor de processos e tarefas programadas do macOS. É o equivalente ao cron + systemd combinados num único sistema. Cada tarefa é definida num ficheiro XML (.plist) que diz ao macOS o que executar, quando, e o que fazer se falhar.

Vamos criar três launchd jobs:

1. Bot de Telegram como daemon permanente (KeepAlive: true).
2. Briefing matinal cada dia às 08:00.
3. Briefing vespertino cada dia às 19:00.

Primeiro o wrapper scripts/run_briefing.sh que lança o Claude Code em modo não interativo para gerar o briefing:

Agora o .plist do briefing matinal. Guarda-o em scripts/launchd/com.kiwop.pa-briefing-morning.plist:

Chave importante: o `PATH` explícito em EnvironmentVariables. O launchd não herda o teu PATH do shell, pelo que se não lho passares, claude não estará disponível e o briefing falhará silenciosamente. Inclui /opt/homebrew/bin (Apple Silicon), /usr/local/bin (Intel) e ~/.local/bin (se instalaste Claude Code via pip --user).

Duplica o ficheiro para o vespertino trocando morning por evening e a hora para 19. E cria o do bot de Telegram:

O trio RunAtLoad: true + KeepAlive: true + ThrottleInterval: 15 significa: arranca ao iniciar sessão, reinicia se cair, e não tentes reiniciar mais rápido do que a cada 15 segundos (para evitar ciclos de falha).

Para ativar os três .plist:

Para verificar que estão ativos:

Devias ver as três entradas com PID (para o bot, que corre continuamente) ou com - (para os briefings, que só correm às suas horas).

Para disparar um briefing manualmente sem esperar pelas 08:00 (útil para testing):

Passo 6: comandos slash /morning, /evening, /inbox, /reply

Os comandos slash do Claude Code vivem em .claude/commands/ como ficheiros Markdown. Cada ficheiro é um prompt template que o Claude executa quando invocas /nome na sessão. São a forma mais limpa de encapsular fluxos repetitivos sem repetir o mesmo prompt longo de cada vez.

Para o PA definimos quatro comandos mínimos: /morning, /evening, /inbox, /reply. Este é o exemplo de .claude/commands/morning.md:

Buenos días — <fecha>

Agenda de hoy

• HH:MM–HH:MM · Título · (lugar / asistentes)

Correo (N no leídos)

🔥 Fuego: [UID] Remitente — Asunto · contexto ⚠ Importante: [UID] ... Para revisar: [UID] ... Ruido: N items

Slack

🔥 ... ⚠ ...

Prioridades sugeridas

1. ...
2. ...
3. ...

O comando /reply é particularmente importante porque aplica a regra de confirmação:

Repara no padrão: o comando faz cumprir a regra de confirmação ao nível de prompt (passo 5), e o script faz cumprir a regra ao nível de execução (o --yes obrigatório em mail_send.py). Dupla camada. Se o modelo "esquecer" o passo 5, o script não envia. Se alguém modificar o script para saltar --yes, o prompt continua a exigir confirmação. É a mesma filosofia de defesa em profundidade que recomendamos em projetos de integração de LLMs para qualquer ação com efeitos irreversíveis.

Os quatro comandos base são suficientes para 90% do uso diário. Podes adicionar mais: /schedule (criar reuniões), /book (agendar a partir de um convite), /auth (diagnóstico do estado dos MCPs).

Passo 7: testar o setup end-to-end

Com tudo montado, chega uma ronda de testes completa antes de o dar por funcional. Esta é a checklist que usamos na Kiwop cada vez que replicamos o setup noutra máquina:

1. MCPs autenticados. Numa sessão de Claude Code a partir de ~/Dev/PA:

Os quatro servers devem aparecer com tools disponíveis. Se algum disser "not authenticated", repete o OAuth.

2. Correio IMAP funcional. A partir do terminal:

Deveria devolver um JSON com os teus três correios não lidos mais recentes. Se falhar com imaplib.IMAP4.error, revê Keychain e portos.

3. Briefing manual. A partir de sessão interativa de Claude Code:

Gera um briefing completo. Não deve demorar mais do que 60 segundos.

4. Bot de Telegram bidirecional. A partir do Telegram, para o teu bot:

• /ping → pong (imediato)
• "o que tenho hoje na agenda?" → resposta com a agenda real (30-40 segundos)

5. Logs de launchd sem erros.

O telegram_bot.err.log deve ter uma linha "Bot up. Allowed chat=...". Se houver um FATAL: secret read failed, revê que o Keychain tem os itens PA-telegram-bot-token e PA-telegram-chat-id.

6. Teste a frio do briefing programado.

Deve ter gerado o briefing do dia e enviado uma cópia para o teu Telegram. Se o Telegram não receber, revê as credenciais PA-telegram-* no Keychain.

Problemas comuns e como diagnosticá-los:

Uma vez passados os seis pontos da checklist, o PA está pronto para uso diário. A partir daqui é tudo refinar: adicionar memory/ com as tuas preferências de estilo, adicionar mais comandos slash consoante os fluxos que detetes repetitivos, ajustar os prompts de morning.md e evening.md ao output exato que te resulta mais útil.

Conselho prático sobre os primeiros sete dias. Depois de o montares, o PA vai fazer coisas subótimas até descobrires o que lhe falta de contexto sobre ti. Recomendamos começar em modo "só leitura" na primeira semana: deixa-o gerar briefings, deixa-o triar a inbox, mas não uses /reply nem confirmes ações de escrita ainda. Durante essa semana irás detetando padrões a corrigir — "classifica mal os correios deste cliente porque não sabe que é VIP", "resume demasiado as mensagens curtas de Slack", "marca como ruído coisas que para mim são importantes". Todas essas correções vão para memory/triage_rules.md e para o CLAUDE.md. A partir do dia sete ou oito, quando a triagem estiver consistente a 85-90%, já podes abrir o uso de escrita com /reply e começar a ganhar tempo real. Saltar esta fase de calibração é o erro mais comum e a causa principal de abandonos na nossa amostra de pessoas a quem ajudámos a montá-lo.

Variantes e escalado: Linux, Windows, e a correr 24/7

O tutorial está escrito sobre macOS porque é onde trabalhamos, mas a arquitetura é portável. Os quatro ajustes principais:

Gestor de processos.

Um unit de systemd para o bot de Telegram em Linux seria aproximadamente assim (~/.config/systemd/user/pa-telegram.service):

Ativação: systemctl --user daemon-reload && systemctl --user enable --now pa-telegram.service.

Armazém de segredos.

O fallback para variáveis de ambiente num ficheiro com permissões 600 funciona nas três plataformas e é o denominador comum se quiseres um único código para todos os sistemas.

launchd vs systemd, comparação honesta:

Correr 24/7 num servidor remoto? É viável e já o testámos. O padrão: um pequeno VPS Linux com systemd a correr o bot de Telegram e os briefings programados, mais uma ligação IMAP/SMTP à caixa, mais o CLI do Claude Code autenticado com a tua conta Anthropic. Vantagens: o PA responde mesmo que o teu portátil esteja desligado. Desvantagens: o OAuth dos MCP servers é mais delicado sem browser local (terás de fazer o fluxo inicial na tua máquina e copiar o refresh token), e qualquer atualização do CLI do Claude Code requer SSH e deploy. Para a maioria de profissionais que usam o Mac diariamente, mantê-lo em local é a opção com melhor relação simplicidade/utilidade.

O salto para um PA multi-utilizador (um que sirva uma equipa) não é uma variante do mesmo tutorial — é um SaaS e requer decisões arquitetónicas muito distintas (multi-tenancy, autenticação, isolamento de sessões). Se te interessa explorar essa rota, abordamo-la nos projetos de desenvolvimento de agentes IA à medida.

Duas extensões que vimos funcionar na prática quando o PA base já está estável. A primeira é uma memory/ povoada com ficheiros Markdown que o Claude carrega em cada sessão: um triage_rules.md com os teus critérios exatos para classificar correio, um writing_style.md com exemplos de correios escritos por ti para que os rascunhos soem à tua voz, um vip_contacts.md com os endereços que nunca devem cair em "ruído". A segunda é um watcher de correio em segundo plano (um daemon similar ao bot de Telegram, mas que em vez de escutar Telegram escuta a tua caixa IMAP) que dispara uma notificação quando chega um correio marcado como fogo segundo as tuas regras — útil para fluxos onde não basta o briefing das 08:00. Ambas as extensões constroem-se com a mesma filosofia que o resto: scripts curtos, segredos no Keychain, sessões efémeras de Claude Code.

Perguntas frequentes

Quanto custa realmente construir este PA?

Se já tens Claude Max x20 (cerca de 200 dólares por mês), o custo marginal do PA é zero. Os MCP servers são gratuitos, o bot de Telegram corre no teu Mac sem hosting, e os scripts Python não requerem dependências pagas. Se não tens Claude Max, o cálculo muda: os 200 dólares por mês são o investimento fixo. O tempo de construção seguindo este tutorial é de 60-90 minutos.

É seguro dar acesso ao meu correio e calendário a um PA construído assim?

Sim, com as seguintes condições explícitas. Primeiro, os MCP servers oficiais autenticam por OAuth sem guardar a tua password em disco — o token vive num armazém cifrado do próprio MCP server. Segundo, as credenciais IMAP/SMTP estão em macOS Keychain (chaveiro do sistema operativo, cifrado), nunca em ficheiros simples. Terceiro, o bot de Telegram só responde ao chat_id whitelisted e a regra de confirmação obrigatória em CLAUDE.md impede ações de escrita sem "sim" explícito. A superfície de ataque fica muito limitada, comparável à de qualquer cliente de correio de secretária.

E a privacidade dos dados? A Anthropic treina com os meus correios?

A Anthropic declara publicamente (política a 2026) que os dados enviados por API e por Claude Code não são usados para treinar modelos. Para conteúdo regulado (sanitário, legal com segredo profissional, financeiro confidencial), convém rever os termos específicos vigentes e considerar se um PA sobre infraestrutura própria é mais apropriado — caso em que uma solução de RAG empresarial pode ser a alternativa correta.

Pode integrar-se WhatsApp neste PA?

À data de abril de 2026 não existe um MCP oficial de WhatsApp. Há bridges não oficiais (Matrix, Beeper, a própria WhatsApp Business Cloud API da Meta) que se podem ligar como um canal adicional, mas todos têm caveats: os bridges não oficiais podem violar ToS da Meta e ser instáveis, e a Business Cloud API requer uma conta comercial verificada. A nossa recomendação pragmática é usar Telegram como canal móvel primário.

Este PA pode dar serviço a vários utilizadores?

Não, por desenho. Um PA é single-user: as suas credenciais, a sua memória, as suas preferências, e o seu CLAUDE.md apontam para uma única pessoa. Para cenários multi-utilizador (uma equipa que partilha um assistente comum) a arquitetura correta é um SaaS multi-tenant com isolamento de dados por utilizador — não uma cópia do PA com variáveis partilhadas. É uma conversa totalmente distinta.

Funciona sem ligação à internet?

Não. O Claude Code requer ligação para consultar o modelo, os MCP servers usam APIs online (Google, Slack, Telegram), e IMAP/SMTP obviamente também. O PA descrito aqui é um cliente que orquestra serviços cloud — não um modelo local. Se precisas de operação offline, é um redesenho completo com um LLM local (Llama, Mistral) a correr em ollama ou similar, com restrições de qualidade e desempenho notáveis.

Quanto tempo demora o PA a dar o seu primeiro briefing matinal?

O run_briefing.sh completo demora entre 40 e 90 segundos consoante a quantidade de correio que tenhas para triar. A parte mais lenta é o fetch IMAP com --with-body (uma ligação por UID), seguido do raciocínio do modelo sobre a triagem. Se a tua caixa for muito grande (>50 não lidos), pode subir para 2-3 minutos. Se for a primeira execução e o MCP de Calendar ainda estiver a aquecer, acrescenta 5-10 segundos extra.

Posso personalizá-lo para o meu fluxo concreto?

Sim, e é a filosofia do projeto. Os ficheiros chave a tocar: CLAUDE.md (persona, tom, regras), .claude/commands/*.md (fluxos concretos), memory/ (preferências persistentes, assinatura, contactos VIP, regras de triagem). O código Python raramente é preciso tocar salvo para adicionar contas IMAP adicionais ou integrar um canal novo. Começa com o setup base a funcionar antes de personalizar — é mais barato aprender onde personalizar quando já vês o que te sobra e o que te falta.

Conclusão: 60 minutos entre ti e o teu primeiro PA operativo

Levamos duas semanas a usar este PA na Kiwop e a conclusão mais honesta que podemos escrever é que o salto de produtividade real não vem do modelo — vem do desenho minimalista em torno do modelo. Claude Code, Opus 4.7, os MCP servers: são a parte cara que não constróis tu. As cerca de 500 linhas de Python, o punhado de ficheiros Markdown, os três .plist do launchd — é isso que fazes tu, e é isso que converte as capacidades do modelo num assistente útil para o teu dia.

Este tutorial cobriu o caminho completo desde um diretório vazio até um PA operativo com quatro canais e briefings programados. O código de referência que usámos está publicado em https://github.com/purroy/majordomo sob uma licença permissiva — clona, faz-lhe fork, adapta-o. Não é a única maneira de construir um PA em 2026, mas é uma que sabemos que funciona porque a usamos todas as manhãs às 08:00 antes de ligar o Mac do trabalho.

Se enquanto seguias o tutorial encontraste um buraco onde o teu caso concreto precisa de mais do que este stack base — integrações à medida com o teu CRM, um canal de Teams, um MCP proprietário para o teu ERP, ou diretamente um assistente multi-utilizador para toda a tua equipa — na Kiwop construímos essas peças como parte dos nossos serviços de desenvolvimento de agentes IA e consultoria de IA. O nosso ponto de partida é sempre o mesmo: camadas finas, desacopladas, agnósticas ao fornecedor. Não há nada neste tutorial que não possas replicar tu mesmo numa tarde, mas se o tempo for mais caro do que o custo de externalizar, contacta a nossa equipa e fazemo-lo contigo.

O PA que tens agora a correr no teu Mac é teu. Ninguém o pode cortar de um dia para o outro. E isso, em 2026, é a propriedade mais valiosa que pode ter um agente IA aplicado ao trabalho diário.