Como sessões do Claude Code enviam mensagens entre si

O que significa as sessões do Claude Code enviarem mensagens entre si

Duas sessões do Claude Code podem enviar mensagens entre si quando são executadas na mesma máquina, com o mesmo utilizador do sistema operativo. Uma mensagem é um texto simples que uma instância do Claude escreve para outra. Não inclui histórico da conversa nem ficheiros. O Claude encontra a outra sessão com a ferramenta ListAgents e entrega o texto com SendMessage, por isso nunca chama nenhuma das ferramentas manualmente. Basta indicar o que a outra sessão precisa de saber, e o Claude escreve a mensagem.

Esta funcionalidade chama-se mensagens entre sessões. Em agosto de 2026, requer o Claude Code v2.1.224 ou posterior e funciona no macOS e no Linux, incluindo Linux dentro do WSL 2. Não existe suporte nativo para Windows, e a funcionalidade não está disponível no Amazon Bedrock, no Claude Platform on AWS, no Google Cloud's Agent Platform nem no Microsoft Foundry. Quando uma sessão cumpre estes requisitos, as mensagens já estão ativas e não é necessário ativar nada. O comportamento descrito abaixo baseia-se na documentação da Anthropic sobre mensagens entre sessões.

É num VPS que isto é relevante, porque é num VPS que as sessões permanecem ativas tempo suficiente para valer a pena contactá-las. Num portátil, fecha-se a tampa. Num servidor com tmux, uma sessão iniciada na segunda-feira continua em execução na quinta-feira e mantém o contexto de um repositório. Quando existem duas sessões desse tipo, a forma como comunicam deixa de ser apenas teórica. Se ainda não configurou esse ambiente, comece por executar o Claude Code num VPS com tmux, que explica a configuração das sessões pressuposta neste guia.

Quando uma segunda sessão compensa o custo

Comece pelo custo. Cada sessão é uma instância separada do Claude, com a sua própria janela de contexto. Por isso, duas sessões custam aproximadamente o dobro de uma sessão no mesmo período. Uma mensagem entregue conta para a utilização exatamente como um prompt que escreveu. A coordenação não é gratuita. Um trabalho que é realmente uma sequência única de passos fica mais lento e mais caro quando é dividido entre sessões.

Os casos em que uma segunda sessão compensa têm uma característica em comum. Duas partes do trabalho são executadas ao mesmo tempo, sem depender uma da outra, e uma delas obtém durante a tarefa uma informação de que a outra precisa.

• Uma sessão encontra uma alteração incompatível enquanto a outra desenvolve sobre o código afetado. O Claude resume a alteração e envia-a, em vez de ter de a escrever novamente no outro terminal.
• Duas sessões trabalham no mesmo repositório, em git worktrees separados, e uma precisa de saber o que foi integrado.
• Uma migração longa ou uma execução de testes comunica o resultado à sessão que está a acompanhar.
• Uma sessão de desenvolvimento e uma sessão de revisão, em que a sessão de revisão lê o que a sessão de desenvolvimento produziu e envia as conclusões.

Quando o trabalho é sequencial ou quando ambas as sessões editariam os mesmos ficheiros, use uma única sessão. Quando pretende um grupo coordenado que o Claude cria e supervisiona dentro de uma única tarefa, está a usar agent teams, uma funcionalidade separada e ainda experimental. Quando pretende apenas a mesma conversa noutro terminal, retome a sessão. As mensagens entre sessões destinam-se a sessões independentes que inicia e controla diretamente.

Verifique se o recurso existe antes de basear o plano nele

Primeiro, verifique a versão:

claude --version

Compare o número com 2.1.224. Em seguida, dentro de uma sessão, digite /list-agents, que também responde a /peers. O comando mostra todos os agentes que esta sessão consegue alcançar, com o nome ao qual cada um responde. Se o comando não for reconhecido, esta sessão não tem mensagens entre sessões, e nenhum ficheiro de definições alterará isso. Digite /status e procure uma linha Peer address: ela contém o endereço da caixa de entrada da própria sessão, com o prefixo uds:.

Há uma armadilha que afeta especificamente os utilizadores de VPS. As mensagens entre sessões dependem da avaliação de sinalizadores de funcionalidades, e várias variáveis de privacidade desativam essa avaliação, deixando o recurso desativado por predefinição. DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC e DISABLE_GROWTHBOOK fazem isso. É comum reforçar um servidor novo colando essas variáveis em ~/.bashrc e depois não perceber por que motivo /list-agents não existe. Os mesmos valores podem vir do mapa env num ficheiro de definições ou de definições geridas, por isso verifique primeiro a shell.

env | grep -E 'DO_NOT_TRACK|DISABLE_TELEMETRY|DISABLE_GROWTHBOOK|NONESSENTIAL'

Remova a definição de qualquer variável que produza saída. Para DISABLE_TELEMETRY e CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, qualquer valor não vazio ativa o comportamento, incluindo a cadeia 0, por isso DISABLE_TELEMETRY=0 não faz o que parece fazer. Para o desativar, remova a definição da variável ou atribua-lhe uma cadeia vazia.

Dê nomes às suas sessões, ou o Claude não poderá endereçá-las

O Claude endereça uma mensagem a uma sessão pelo nome. Defina o nome ao iniciar a sessão:

claude --name builder-api

Também pode defini-lo com /rename dentro de uma sessão em execução. Se não definir nenhum nome, o Claude Code gera um nome a partir do nome da pasta do diretório de trabalho, como myapp-3f. Isto é adequado para uma sessão, mas fica confuso com quatro, e duas sessões podem acabar com o mesmo nome. O resultado de /list-agents mostra o diretório de trabalho de cada sessão local, o que permite distinguir sessões com o mesmo nome, e a própria listagem do Claude acrescenta um identificador curto ao endereço quando há nomes duplicados. Dar-lhes nomes manualmente custa menos do que consultar identificadores.

Um layout do tmux com duas sessões que pode reproduzir

Esta é uma sessão de implementação e uma sessão de revisão no mesmo repositório. A sessão de revisão trabalha num git worktree separado, por isso as duas nunca escrevem no mesmo ficheiro. git worktree add com HEAD fornece um checkout desanexado, que é o que pretende para uma sessão que lê, mas não faz commits.

cd ~/src/api
git worktree add ../api-review HEAD
tmux new-session -d -s agents -n builder -c ~/src/api
tmux new-window -t agents -n reviewer -c ~/src/api-review
tmux send-keys -t agents:builder 'claude --name builder-api' C-m
tmux send-keys -t agents:reviewer 'claude --name reviewer-api' C-m
tmux attach -t agents

Ctrl+b e depois w lista as janelas pelo nome, para que possa escolher uma. Na janela de implementação, execute /list-agents. Deverá ver reviewer-api com o diretório de trabalho ~/src/api-review. Se estiver em falta, a sessão de revisão ainda não terminou de arrancar ou aplica-se um dos dois problemas da secção seguinte. Depois, transmita algo em linguagem simples:

Tell reviewer-api which files I changed for the rate limiter and what to look at first.

Claude escreve o resumo e envia-o. Não escreve o texto da mensagem, e o conteúdo enviado por Claude varia. Na janela de revisão, a mensagem aparece na conversa com o nome do remetente. Se essa sessão estiver inativa, Claude inicia imediatamente uma nova interação nela. Se estiver a executar uma interação, a mensagem aguarda até entre chamadas de ferramentas, para que um comando em execução nunca seja interrompido. Depois de Claude a ler, a mensagem é reduzida a uma linha Message from que Ctrl+O expande. O par funciona melhor quando a sessão de implementação mantém as alterações pequenas, porque um diff restrito produz uma passagem de contexto mais curta e uma revisão que a outra sessão consegue concluir numa interação, que é o hábito que a competência do programador sénior preguiçoso existe para impor.

Quem pode ver quem num único VPS

A entrega dentro da mesma máquina nunca passa pelos servidores da Anthropic. Cada sessão escreve ficheiros de registo no disco e associa o seu próprio socket de caixa de entrada. O Claude Code lê esses ficheiros para encontrar as outras sessões. Daqui resultam duas consequências, e ambas são importantes num servidor.

O socket está restrito ao seu utilizador do sistema operativo. Uma sessão iniciada como root e uma sessão iniciada como deploy não conseguem ver-se, mesmo lado a lado no mesmo servidor tmux, porque as sessões de um utilizador não conseguem aceder ao socket de outro utilizador. Execute ambas as sessões com o mesmo utilizador.

Um contentor tem o seu próprio sistema de ficheiros. Uma sessão dentro do Docker e uma sessão no host não conseguem comunicar, porque não leem os mesmos ficheiros de registo. Duas sessões dentro do mesmo contentor podem trocar mensagens normalmente. Se mantiver os agentes em contentores para isolamento, como em executar agentes de programação numa VM descartável, espere que as mensagens funcionem dentro de um contentor, mas não através do limite do contentor.

As suas sessões noutras máquinas e na web aparecem na listagem apenas enquanto o Remote Control está ligado, e são identificadas como tal. O Claude aqui só pode responder a uma mensagem recebida de uma dessas sessões. Não pode iniciar essa troca.

Por que a sua mensagem nunca chegou

O motivo habitual não tem relação com a rede. A sessão recetora decidiu o que fazer com a mensagem, e decidiu não a entregar. Cada mensagem recebida termina num de três estados: entregue, retida (mantida sem entrega até à sua aprovação) ou recusada (descartada sem entrega).

Quando não se aplica nenhum valor crossSessionInbound, o Claude Code decide por mensagem comparando os modos de permissão das duas sessões. Agrupa numa classe as sessões que ignoram os pedidos de permissão e coloca todas as outras na outra classe. auto, acceptEdits e dontAsk contam como modos que pedem confirmação. O modo de planeamento conta como modo que ignora pedidos numa sessão que tem permissões para os ignorar. A regra é, portanto, simétrica:

• Uma sessão recetora que pede permissões recebe cada mensagem. Retém uma mensagem apenas quando a sessão emissora se identifica como uma sessão que ignora pedidos de permissão.
• Uma sessão recetora que ignora pedidos de permissão retém todas as mensagens para sua aprovação. Entrega uma mensagem apenas quando a emissora também ignora esses pedidos.

Por isso, o primeiro fluxo de trabalho que a maioria das pessoas cria é precisamente o que não funciona. Inicia um builder com --permission-mode bypassPermissions porque quer que ele seja executado sem supervisão, mantém o reviewer com os valores predefinidos e todas as mensagens enviadas pelo builder ficam à espera numa caixa de diálogo de aprovação que ninguém está a acompanhar. Essa caixa de diálogo fecha-se depois do prazo dialogExpiry, cujo valor predefinido é 5m, e a mensagem é descartada. Na mesma máquina, a sessão emissora recebe uma notificação quando a sua mensagem é retida e outra quando a recetora a entrega, recusa ou deixa expirar. Por isso, leia o ecrã da sessão emissora antes de atribuir a falha ao socket.

Para permitir que uma sessão receba mensagens sem supervisão, defina crossSessionInbound como accept. O local onde define esta opção determina onde ela se aplica. O Claude Code lê primeiro as definições geridas, depois a flag --settings e, por fim, as definições do utilizador. Aplica o primeiro valor encontrado. Um valor nas definições do projeto ou locais só se aplica quando é mais restritivo, na ordem accept < hold < refuse. Um accept em .claude/settings.json é menos restritivo do que qualquer valor, por isso é ignorado sempre que uma fonte fidedigna tiver definido um valor. Coloque-o em ~/.claude/settings.json ou passe-o para uma única sessão:

claude --name runner --settings '{"crossSessionInbound":"accept"}'

Um worker claude -p sem interface associa um socket de caixa de entrada como uma sessão interativa e aparece na listagem, mas não consegue mostrar uma caixa de diálogo de aprovação. Uma mensagem retida nesse worker permanece retida até que uma alteração posterior do modo ou das definições permita a sua entrega. A linha --settings acima é a forma de permitir que esse worker receba mensagens. Uma sessão iniciada no modo bare não associa nenhum socket. Por isso, não pode receber mensagens nem aparecer na lista.

Quando as transferências ficam bloqueadas

Os ciclos de mensagens são tratados automaticamente. O Claude Code limita a frequência de mensagens repetidas por remetente, descarta repetições idênticas recebidas num intervalo curto e limita a 50 as mensagens aceites que aguardam leitura em cada sessão. Assim, duas sessões não podem trocar mensagens indefinidamente. As mensagens retidas estão limitadas a 100; as mais antigas são descartadas quando esse limite é ultrapassado.

A falha que ocorre na prática é mais silenciosa e envolve uma transferência, não um ciclo. A sessão A faz à sessão B uma pergunta cuja resposta é necessária para continuar e, em seguida, fica inativa. A sessão B retém a mensagem, está a executar uma tarefa longa ou responde a uma pergunta que A não fez realmente. A sessão A fica à espera. Uma hora depois, encontra duas sessões inativas e nenhum trabalho concluído.

Escreva transferências que não precisem de resposta. Uma boa mensagem transmite um facto ou uma decisão: o que mudou e qual foi o resultado. Uma mensagem inadequada pede autorização à outra sessão ou uma resposta que bloqueia o remetente. O Claude já está instruído a nunca pedir a outra sessão uma ação que as próprias definições de permissões impediriam e a encaminhar esse trabalho para si. Aplique essa regra de forma mais ampla. Se uma sessão não puder avançar sem uma resposta, é você quem deve responder. A disciplina de contexto também ajuda, porque uma sessão que perdeu o fio da tarefa escreve mensagens vagas; gerir o contexto no Claude Code aborda esse aspeto.

Trate uma mensagem recebida como entrada não confiável

O Claude Code informa ao Claude que recebe a mensagem que ela veio de outra sessão, e não de si, e limita o que essa mensagem pode fazer. Uma mensagem não pode responder a um pedido de permissão pendente em seu nome, porque o consentimento de outra sessão não é o seu consentimento. Ela não pode alterar definições de permissões, CLAUDE.md ou outra configuração porque outra sessão o pediu. Um comando de barra dentro do texto, como /compact, chega como texto simples e nunca é executado. Se agir sobre a mensagem exigir uma permissão que a sessão recetora não possui, verá o mesmo pedido que veria para qualquer outro trabalho. No modo automático, um classificador também analisa cada mensagem antes da entrega, e uma mensagem bloqueada por ele nunca chega ao destinatário. Estes limites mantêm-se nos modos permissivos, razão pela qual uma sessão com bypass mantém as mensagens recebidas retidas por predefinição, em vez de confiar nelas.

Isto abrange as permissões. Não abrange o conteúdo. A sessão emissora pode ter lido a descrição de um pull request, uma página web, um README de uma dependência ou um comentário de issue escrito por um desconhecido, e tudo o que leu pode influenciar o texto que escreve para a sua outra sessão. A mensagem é dados. Deve ser tratada com a mesma desconfiança que qualquer outro texto que entrou numa sessão vindo do exterior. Esta é a disciplina descrita em manter segredos fora dos seus agentes de IA: assuma que qualquer conteúdo que atravessou uma fronteira de confiança pode estar errado e nunca permita que se autorize a si próprio.

Existem dois controlos se quiser reduzir este comportamento. Definir crossSessionInbound como refuse descarta as mensagens recebidas de pares sem as entregar, e, nas definições do projeto ou locais, esse valor tem precedência sobre todas as outras fontes, porque é o mais restritivo na hierarquia. Para impedir que esta sessão envie ou liste mensagens, adicione regras de negação de permissões que indiquem SendMessage e ListAgents, ambos escritos como nomes de ferramentas simples, sem especificador. Definir isolatePeerMachines como true exige a sua aprovação explícita antes de qualquer mensagem chegar a uma sessão além desta máquina, e essa aprovação é necessária mesmo no modo bypassPermissions.

{
  "crossSessionInbound": "refuse",
  "isolatePeerMachines": true
}

Negar SendMessage também remove o envio de mensagens para subagentes, porque a mesma ferramenta serve ambos. Uma sessão que recusa mensagens não mostra qualquer alteração visível no seu próprio /status nem nas listagens de outras sessões. Por isso, confirme a definição na configuração da sessão, e não no ecrã.

Bridges e servidores MCP com memória partilhada

Vários projetos de terceiros foram lançados no mesmo período com uma função adjacente: bridges locais entre agentes, que retransmitem texto entre agentes em execução, e servidores MCP (model context protocol), que disponibilizam um armazenamento partilhado para vários agentes lerem e escreverem. Avalie-os como uma abordagem diferente, não como concorrentes, e confirme qualquer comando de instalação no README do próprio projeto antes de o executar. As mensagens usam push, porque o remetente coloca texto no turno do destinatário. Um armazenamento partilhado usa pull, porque ninguém é interrompido e uma sessão vê a nota quando a consulta na próxima vez. O modelo pull é mais adequado para estados que mudam lentamente e só funciona quando uma sessão consulta efetivamente o armazenamento.

Se seguir essa abordagem, as perguntas importantes dizem respeito ao processo, não à lista de funcionalidades. Com que utilizador o servidor é executado e a que dados pode aceder no sistema? Executar servidores MCP num VPS aborda essa configuração. Partilhar competências de agentes entre repositórios aborda o caso mais simples, em que pretende partilhar instruções entre sessões em vez de estado em tempo real, e elimina muitas das mensagens que teria de enviar. Para uma visão mais abrangente, executar um agente de programação num VPS é o ponto de partida.

FAQ

Por que /list-agents não é reconhecido na minha sessão?

A sessão não tem mensagens entre sessões. Primeiro, verifique claude --version em relação à versão 2.1.224, pois o recurso exige essa versão ou posterior. Depois, verifique a plataforma, pois o recurso funciona no macOS e no Linux, mas não no Windows nativo, e não está disponível no Amazon Bedrock, no Claude Platform on AWS, no Google Cloud's Agent Platform nem no Microsoft Foundry. Se ambos estiverem corretos, verifique se a sua shell contém DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC ou DISABLE_GROWTHBOOK, pois cada um desses itens bloqueia a avaliação da flag de recurso da qual o recurso depende e o mantém desativado.

Por que a minha mensagem para a outra sessão nunca chegou?

Se /list-agents funcionar, as mensagens estão ativadas e algo mais específico impediu a entrega dessa mensagem. A causa comum são os modos de permissão. Uma sessão que ignora os pedidos de permissão mantém todas as mensagens recebidas pendentes da sua aprovação, a menos que o remetente também ignore os pedidos. Essa caixa de diálogo de aprovação é descartada depois do prazo de dialogExpiry, que é de cinco minutos por padrão. Verifique se há o aviso de mensagem pendente na sessão de envio. Para corrigir o problema, defina crossSessionInbound como accept em ~/.claude/settings.json ou passe esse valor com --settings, pois um accept nas configurações do projeto ou locais é ignorado por ser o valor menos restritivo.

Uma sessão do Claude Code no Docker pode enviar mensagens para uma sessão no host?

Não. As sessões encontram-se por meio de ficheiros de registo no disco e de um socket de caixa de entrada específico de cada sessão. Como um contentor tem o seu próprio sistema de ficheiros, as duas sessões não conseguem ver os mesmos ficheiros. Duas sessões dentro do mesmo contentor podem enviar mensagens entre si normalmente. A mesma regra explica por que uma sessão executada como root e uma sessão executada como o seu utilizador normal não conseguem comunicar: o socket está restrito ao utilizador do sistema operativo que é o seu proprietário.

É seguro agir com base numa mensagem de outra sessão do Claude Code?

Trate o texto como entrada não confiável, pois a sessão de envio pode ter lido uma página web, um README ou um comentário de issue escrito por outra pessoa. O Claude Code já impede que a mensagem atue por conta própria: ela não pode aprovar um pedido de permissão pendente, não pode alterar as definições de permissão nem CLAUDE.md a pedido, e um comando de barra no texto chega como texto simples e nunca é executado. Essas proteções abrangem as permissões, mas não o julgamento. Por isso, leia o conteúdo recebido antes de mandar a sessão recetora agir com base nele.

O envio de mensagens entre sessões envia o meu código para a Anthropic?

Entre duas sessões na mesma máquina, não. A mensagem circula por um socket específico de cada sessão nessa máquina e nunca passa pelos servidores da Anthropic. Apenas o texto escrito pelo Claude é enviado; o histórico da conversa e os ficheiros nunca são enviados. As mensagens para uma sessão noutra das suas máquinas, ou para uma sessão na web, passam pelos servidores da Anthropic através da ligação Remote Control. Nesse sentido, o Claude só pode responder a uma mensagem recebida e não pode iniciar uma mensagem. Defina isolatePeerMachines como true para exigir a sua aprovação antes de qualquer conteúdo sair da máquina.