Terminais

Estes são os terminais dos quais o Collie lê sessions: Herdr, tmux, zellij, tuios e Tern. O Collie controla um terminal por instalação, e o Herdr é o padrão. Esta página aborda como apontar o Collie para qualquer um deles, o que cada um pode responder e os beacons que o Collie usa para detectar um agente em um painel. Um agente durável sem tela não é um terminal, e Durable agents aborda isso.

O tmux e o zellij chamam seu próprio grupo de nível superior de session. O Collie o mostra como um space.

Apontando o Collie para um multiplexador

Defina o backend em COLLIE_MUX, aponte-o para um endpoint, reinicie e instale os hooks de beacon.

Experimental. tmux e zellij (desde 1.0) foram testados no tmux 3.6b e no zellij 0.44.2, em um único host. O tuios (desde 1.15.0) foi testado no tuios 0.8.4. O Tern foi avaliado pelo seu contribuidor no tern 0.4.5, um beta fechado que os mantenedores não podem executar. O Herdr é o padrão e o backend principal suportado. Procura-se testadores: abra uma issue no AltanS/collie intitulada tmux: …, zellij: …, tuios: … ou tern: …, com seu multiplexador, versão, SO e o que você observou.

Indique o multiplexador na linha de comando:

COLLIE_MUX=herdr collie start
COLLIE_MUX=tmux collie start
COLLIE_MUX=zellij collie start
COLLIE_MUX=tuios collie start
COLLIE_MUX=tern collie start

Defina o endpoint quando o destino padrão não for o desejado:

# in your .env: ~/.config/collie/.env, or Herdr's plugin config dir on a Herdr
# install. See Configure for the full precedence.
COLLIE_MUX=tmux
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock
COLLIE_MUX_ENDPOINT_ZELLIJ=collie-zellij

# only if the binary sits somewhere unusual
# COLLIE_TMUX_BIN=/usr/bin/tmux
# COLLIE_ZELLIJ_BIN=/home/you/.local/bin/zellij

O Herdr não tem variável de endpoint aqui: seu socket é HERDR_SOCKET_PATH, não um nome de COLLIE_MUX_ENDPOINT_.

Aquele socket é o local e nenhum outro. Uma máquina salva no Herdr não é um membro da crew, e apenas uma crew do Collie traz os painéis de outra máquina para o telefone. O que cada lista é, e por que uma não é a outra, está em Máquinas do Herdr e a crew.

Em seguida, reinicie, instale os hooks de beacon e inicie um agente onde o telefone possa vê-lo:

collie restart                 # after every .env edit
collie hooks install claude    # once per host; tmux, zellij and tern need it, Herdr gets hook edges

# open a window or a tab for the agent
tmux -S /run/user/1000/collie-tmux.sock new-window -n claude
zellij --session collie-zellij action new-tab --name claude

claude                         # in that window or tab

O que esses comandos fizeram

COLLIE_MUX na linha de comando define a escolha para essa execução e para todas as seguintes. start grava o nome em .env, de modo que executar collie start mais tarde controla o mesmo multiplexador.

Com COLLIE_MUX não definido, start procura por Herdr, tmux e zellij, solicita a escolha de um backend e grava a resposta em .env. Para a referência completa de configuração, consulte MUX_CONTRACT.md → Apontando um collie para um multiplexador.

collie hooks install claude instala os hooks de beacon do Collie, que tmux, zellij e tern exigem. Eles expõem painéis como shells genéricos; portanto, sem hooks, cada painel aparece como bash.

O comando atualiza ~/.claude/settings.json e deixa as configurações de projeto intocadas (detalhes abaixo). O Claude Code 2.1.301 recarrega seus hooks enquanto executa. Reinicie um Claude mais antigo.

Nota. O Herdr não é necessário neste modo. Com COLLIE_MUX=tmux ou COLLIE_MUX=zellij, a bridge carrega apenas o adaptador selecionado e ignora o socket do Herdr. A descoberta de várias sessões do Herdr entre raízes de configuração do Herdr fica desativada (bridge/index.ts). Você não precisa do Herdr instalado ou em execução, e .env fica em ~/.config/collie/ em vez do diretório de configuração do plugin.

observações sobre o tmux

COLLIE_TMUX_BIN geralmente é deixado sem definição. O Collie verifica uma lista de caminhos padrão e não lê PATH, que serviços em segundo plano e ações do Herdr não compartilham com shells de login.

Nota. Mantenha os caminhos de socket curtos. Sockets de domínio Unix com mais de aproximadamente 100 caracteres falham ao conectar, e o tmux retorna error connecting to … (File name too long). Use /run/user/<uid>/ ou /tmp em vez de um caminho de diretório profundo.

Em versões do tmux anteriores à 3.7 com window-size definido como manual, criar uma janela trava o servidor. O Collie bloqueia a criação de janelas nesse estado e orienta você a executar tmux set -g window-size latest; Requisitos lista as versões testadas.

Com automatic-rename ativado, o tmux renomeia uma janela com o nome do programa que estiver rodando nela; em vez disso, o Collie mostra a última pasta do painel ativo dessa janela, já que uma tela cheia de abas chamadas bash não diz nada. Uma janela que você mesmo nomeou mantém esse nome.

observações sobre o zellij

Se a sua distribuição não tiver pacotes do zellij, baixe um binário em releases do GitHub do zellij e coloque-o no seu PATH.

Deixar o endpoint vazio usa como padrão a única sessão em execução. Se houver zero ou várias sessões, o Collie é interrompido com um erro em vez de selecionar uma. Se uma sessão nomeada for encerrada, o Collie a reporta pelo nome em vez de alternar para uma ativa.

O Zellij requer XDG_RUNTIME_DIR para localizar sessões. Se o Collie reportar que todas as sessões foram encerradas, verifique se o serviço systemd inclui essa variável de ambiente (contrato).

As sessões do Zellij persistem independentemente do terminal inicial. Crie uma sessão com zellij -s collie-zellij e desconecte usando Ctrl o d. Em hosts headless, zellij attach --create-background collie-zellij inicia uma sessão desconectada diretamente (verificado no zellij 0.44.2).

Nota. O Collie gerencia sessões ativas, mas não as cria nem as reinicia.

O Zellij 0.44 e posteriores informam a pasta de cada painel, de modo que os painéis do zellij ganham o botão Files e exibem sua branch. Um zellij mais antigo não informa nenhuma pasta, e seus painéis não têm nenhum dos dois.

notas sobre o tern

Aponte o Collie para o Tern:

COLLIE_MUX=tern collie start
collie hooks install claude   # beacon hooks for agent detection

O Collie lê sessões do Tern como spaces, abas como tabs e blocos como panes. O endpoint é o socket do daemon Tern, usando por padrão $XDG_RUNTIME_DIR/tern/daemon.sock (ou /tmp/tern-<uid>/daemon.sock). Dentro de um painel do Tern, $TERN_PANE identifica o bloco e $TERN_PANE_SOCKET aponta para o socket do daemon.

O Tern reporta eventos de ciclo de vida via tern events, permitindo notificações imediatas de alterações de topologia.

"Show in terminal" move sua janela do Tern para a sessão e aba do Tern do painel e foca o bloco dele. Uma aba ou uma sessão do Tern criada pelo Collie abre em segundo plano e não move sua janela.

O Collie não detecta o Tern por conta própria, da mesma forma que não detecta o tuios: identifique-o com COLLIE_MUX=tern. Textos digitados com mais de 128 KiB são recusados, pois transitam como um único argumento de linha de comando.

notas sobre durable

Um agente durável que você anexa não é um terminal e não tem tela. Durable agents aborda como anexar um com collie durable attach, o formato mais antigo que controla um agente durável sozinho com COLLIE_MUX=durable, as duas maneiras de alcançar um agente durável, o que ele pode fazer no telefone e o que verificar quando ele aparece como inacessível.

notas sobre o tuios

O tuios relata os agentes diretamente, portanto não precisa de hooks de beacon:

COLLIE_MUX=tuios collie start
tuios integration install claude-code   # once, so tuios hears the agent's hooks

O Collie lê o agente, seu estado e sua conversa a partir do daemon tuios. Um painel aguardando você aparece como bloqueado, e o histórico de um painel é aberto quando o agente relata sua conversa. Um agente para o qual o Collie não possui harness aparece como um shell.

O Collie exibe cada sessão do tuios como um espaço, cada workspace como uma aba e cada janela como um painel. Um workspace aparece como uma aba enquanto contiver um painel. Um painel executado em outra máquina não é exibido. Aponte uma instância do Collie nessa máquina para o tuios dela.

O endpoint é o socket do daemon. Deixe em branco para usar o socket utilizado pelo próprio tuios. O Collie lê XDG_RUNTIME_DIR para encontrá-lo; portanto, garanta que o serviço tenha essa variável. Dentro de um painel do tuios, echo $TUIOS_SOCKET exibe o caminho.

O Collie precisa do tuios 0.8.3 ou mais recente: o daemon deve anunciar o evento workspace-renamed, o que a versão 0.8.2 não faz. Com um daemon mais antigo, o Collie mostra a bridge como desconectada e o log indica o que atualizar.

Algumas coisas funcionam de forma diferente no tuios:

• —
  Uma nova aba abre no workspace vazio mais baixo. Uma sessão do tuios tem nove workspaces por padrão, portanto o Collie recusa uma décima aba.
• —
  Show in terminal move todo terminal que exibe a sessão do tuios do painel, incluindo uma aba do tuios-web. O tuios não pode mover um terminal para outra sessão do tuios. Se nenhum terminal exibir a sessão do tuios do painel, o Collie recusa e informa o nome da sessão do tuios que o terminal exibe.
• —
  A opção Nova worktree na página Novo permanece desativada e informa que precisa do Herdr.

Funcionou?

collie doctor   # the `mux` check names the multiplexer, its endpoint,
                # and whether it answered (durable: the six `durable-*` checks)

# `[bridge] mux: tmux · socket /run/user/1000/collie-tmux.sock`, printed at
# startup; a multiplexer it cannot reach is one warning line more
collie logs

# the herd, as the phone is given it; reads need the pairing token
curl -s -H "Authorization: Bearer $COLLIE_TOKEN" http://127.0.0.1:8787/api/snapshot | head -c 400

Toda leitura requer o token de um dispositivo emparelhado, então esta chamada curl envia um. Sem ele, a ponte responde 403 device not paired. Para obter um token para um script, consulte Atualizando para 1.18.0. collie doctor não requer token no host. COLLIE_DEVICE_HEADER ainda restringe apenas gravações e a visualização Files (Parear um dispositivo).

Verifique a interface no celular: o painel deve exibir suas janelas do tmux ou abas do zellij, e o painel do Claude deve se identificar como um agente em vez de bash. Se os painéis ainda aparecerem como shells padrão, verifique a instalação dos hooks de beacon abaixo.

O Collie grava hooks nas próprias configurações do Claude

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Como tmux, zellij e tern expõem painéis como shells genéricos, os agentes precisam se anunciar. Isso exige instalar os hooks de beacon do Collie na configuração do Claude Code. No Herdr, os mesmos hooks fornecem apenas hook edges.

A saída faz referência ao caminho bin/collie deste repositório. As instalações por pacotes usam o caminho do binário instalado (~/.local/bin/collie ou ~/.local/share/collie/current/bin/collie) em vez de diretórios com versão, garantindo que os links permaneçam válidos após atualizações.

Detalhes de comportamento para alterações na configuração do Claude:

• —
  Modifica o global ~/.claude/settings.json e qualquer CLAUDE_CONFIG_DIR ativo. Arquivos .claude/settings.json no nível do projeto não são alterados.
• —
  Injeta cinco hooks marcados como # collie-beacon v1 com tempos limite de 10 segundos. Hooks existentes são preservados. O hooks uninstall claude remove apenas entradas do Collie.
• —
  Não altera sua statusLine a menos que você peça. Sem uma flag, a instalação não mexe no statusLine. Você ainda tem o ponto de contexto ao lado do modelo acima da barra inferior: os hooks leem o transcript da sessão, e o tamanho da janela desde o início da sessão.
• —
  As janelas de 5 horas e de 7 dias aparecem sozinhas. Eles não precisam de hook nem de statusLine. Enquanto um painel do Claude está aberto, a bridge lê o seu login do Claude nesta máquina (~/.claude/.credentials.json, ou $CLAUDE_CONFIG_DIR/.credentials.json; as Chaves em um Mac sem arquivo) e consulta api.anthropic.com/api/oauth/usage, a mesma chamada que o /usage do Claude Code faz. Ela consulta quando o painel surge, após o fim de um turno (no máximo uma vez por minuto) e a cada cinco minutos. Ela não armazena nada do login, nunca o atualiza e não o envia para nenhum outro lugar. Ela ignora arquivos de login legíveis por outros (qualquer permissão mais aberta que 0600) e logins expirados, sendo que o Claude Code atualiza esses na próxima chamada dele. Sessões com chave de API, Bedrock ou Vertex não têm janelas para exibir. Painéis do Codex obtêm as suas do mesmo jeito, no mesmo intervalo, a partir de seus próprios arquivos de sessão sem ler logins. OpenCode Go e Grok ficam desativados até que você os especifique, com COLLIE_ACCOUNT_WINDOWS=all ou uma lista (veja Janelas de uso). COLLIE_ACCOUNT_WINDOWS=0 (ou [bridge] account_windows = false) desativa tudo isso, e collie doctor indica quais na linha account-windows.
• —
  Encapsular sua statusLine é o segundo caminho. Com collie hooks install claude --statusline, o Collie também envolve sua própria statusLine, e as janelas vêm do que o Claude Code repassa a ela. Use esta opção se preferir isso em vez da leitura do login, com COLLIE_ACCOUNT_WINDOWS=0. O comando dela se torna collie beacon statusline …, e seu script continua rodando e imprimindo como antes. O Collie nunca adiciona uma statusLine, e hooks uninstall claude restaura seu comando com exatidão. Uma instalação sem a flag mantém o encapsulamento existente e o aponta para o binário atual. Para remover um encapsulamento indesejado, execute collie hooks uninstall claude e depois collie hooks install claude sem --statusline. Não funciona no Windows.
• —
  Para alterar uma statusLine encapsulada, remova o encapsulamento primeiro. Execute collie hooks uninstall claude, edite statusLine.command, depois execute collie hooks install claude --statusline novamente. O comando encapsulado referencia o binário do collie pelo caminho; portanto, se esse binário mudar de lugar, a statusLine não imprimirá nada até que você execute a instalação de novo. collie update lembra você quando uma statusLine encapsulada apontar para um binário antigo. Para testar o wrapper manualmente, execute-o fora do multiplexador (env -u HERDR_PANE_ID -u TMUX_PANE -u ZELLIJ_PANE_ID …), caso contrário ele registrará uma leitura em todas as bridges em execução.
• —
  O Claude Code recarrega seus hooks enquanto executa. Isso vale para a 2.1.301. Reinicie um Claude mais antigo se nenhum hook edge chegar.
• —
  Apenas Linux. A verificação de atividade do agente depende do /proc. Outros sistemas operacionais não emitem beacons.
• —
  Beacons são específicos do multiplexador. Eles registram identificadores de painel e sessão para o backend ativo. Alternar o COLLIE_MUX invalida beacons existentes. Beacons antigos permanecem no disco até serem limpos, visíveis na contagem de beacons do collie doctor.
• —
  Se estiver usando COLLIE_STATE_DIR, exporte-o no ambiente de shell do agente. O collie beacon emit lê essa variável diretamente; caso contrário, os beacons gravam no diretório de estado padrão, onde a ponte não os encontrará.

O collie doctor inclui uma verificação de diagnóstico beacon-hooks-claude que aponta hooks ausentes ou caminhos corrompidos para checkouts movidos. Para obter detalhes sobre o tempo de execução, consulte Beacons de agentes.

O que muda em comparação com o Herdr

A tabela abaixo resume as principais diferenças. Consulte MUX_CONTRACT.md para ver a especificação exata.

Sem beacons ativos, tmux, zellij e tern apresentam painéis como shells puros, e o histórico do painel é marcado como indisponível em vez de retornar conteúdo vazio.

Duas coisas que parecem diferentes no celular

• —
  "sincronizado há Ns": Este indicador aparece no cabeçalho do painel para mostrar a idade dos dados. Ele é exibido apenas quando o backend depende de polling agendado, como zellij (intervalo de polling de até 12 s). O Herdr e o tmux enviam alterações de estado imediatamente, portanto o selo de atualização recente é omitido.
• —
  "Mostrar no terminal": Esta ação de painel foca o painel selecionado no terminal host ativo. Ela fica desativado no zellij porque o comando de foco do zellij aceita a instrução sem alterar o estado de visualização.

Nota. A interface móvel nunca altera o foco do terminal host automaticamente. Apenas a ação explícita "Mostrar no terminal" atualiza a exibição. Navegar pelo painel ou abrir painéis não afeta o cursor ativo do host (ADR 0031).

dicas do tmux, recuperando suas janelas após uma reinicialização

claude --resume      # reconnects the conversation, not the window

O Collie não armazena o estado do multiplexador. Reiniciar um servidor tmux destrói suas janelas, deixando o painel vazio. Plugins padrão do tmux restauram os layouts de janela e diretórios de trabalho: tpm para gerenciamento de plugins, tmux-resurrect para salvar árvores de sessões e tmux-continuum para snapshots automatizados.

Nota. Processos de agentes em execução não são preservados. Reinicie o Claude Code manualmente após a recuperação.

dicas do zellij, após uma reinicialização não há nada para restaurar

zellij -s collie-zellij                                  # start the session
zellij attach --create-background collie-zellij          # headless: start it detached
claude --resume                                           # reconnects the agent

O Zellij não fornece um equivalente ao tmux-resurrect. Sessões mantidas após o desanexo do terminal são exibidas como (EXITED - attach to resurrect), e o anexo dispara a reexecução dos comandos da sessão; portanto, uma reinicialização exige iniciar a sessão do zero com um dos comandos acima e iniciar agentes dentro dela, reconectando cada um com claude --resume ou claude --continue.

Nota. Como a conexão produz efeitos colaterais, o Collie não se conecta a sessões nem as ressuscita. Sessões encerradas aparecem como inacessível, e a interface exibe um banner de desconexão em vez de uma lista de sessões vazia.

Beacons de agentes (opcional, Linux)

Um beacon é a forma como um agente se identifica para o Collie, no tmux, zellij e tern, onde, de outro modo, um painel apareceria como um shell genérico.

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Um hook nas configurações do Claude Code executa collie beacon emit, que grava um arquivo contendo o nome do harness, a sessão e o painel de destino. O Herdr rastreia isso nativamente. Detalhes de configuração estão em Apontando o Collie para um multiplexador; esta seção explica o mecanismo.

O caminho acima referencia bin/collie a partir do checkout local. Uma instalação binária aponta para ~/.local/bin/collie, ou para ~/.local/share/collie/current/bin/collie quando esse nome não estiver vinculado, como descrito acima. O comando status não realiza gravações.

Executar hooks uninstall claude remove apenas entradas adicionadas pelo Collie. Isso modifica sua configuração do Claude em global, não arquivos no nível do projeto. Isto é exclusivo para Linux: a verificação de atividade inspeciona /proc, e o Collie não grava beacons em outros sistemas operacionais.

O Claude torna-se visível imediatamente na inicialização. Como o hook é disparado em SessionStart, um painel aberto aguardando entrada é exibido como um agente ocioso em vez de um shell.

A visibilidade termina quando o processo é encerrado. O Collie verifica o PID emissor a cada checagem; portanto, assim que o agente finaliza, o painel é imediatamente reportado como um shell padrão em vez de permanecer em um estado desconhecido.

O Collie não exclui o arquivo de beacon para fazer isso: o arquivo permanece no disco, collie doctor o reporta sob beacons como expirado, e a próxima invocação do hook o sobrescreve.

Isso permite que o painel rotule os painéis pelo nome do agente em vez de bash. Permite "needs you" ordena os painéis pelo status de bloqueio e fornece o estado necessário para alertas. O histórico do painel também depende do beacon para fornecer a chave de sessão usada pelo journal.

Hook edges

Os mesmos hooks também gravam um hook edge para cada evento. Um hook edge é uma nota curta sobre um painel. Exemplos são "um prompt entrou", "o turno parou" e "uma caixa de diálogo de permissão está aberta". O Collie usa hook edges em todo multiplexador, inclusive no Herdr. O Herdr nomeia seus agentes por conta própria. No Herdr, portanto, os hooks gravam apenas hook edges, e nenhum beacon.

Uma transição de hook nunca decide por conta própria que um painel está livre. Após cada transição, o Collie lê a tela novamente cerca de 0,7 segundos depois. Apenas a tela pode indicar que a caixa de entrada está vazia e nenhuma caixa de diálogo está aberta. Uma transição pode indicar que um turno está em execução ou que uma caixa de diálogo está aberta. O Collie então mantém o painel como ocupado até que a transição de fechamento ocorra. Três leituras de tela livre ao longo de dez segundos também encerram essa retenção. Uma transição de ferramenta de um subagente não se refere ao painel, portanto nunca altera o que o Collie lê ali.

Um envio feito pelo telefone pode aparecer como Confirmed. Isso acontece quando um prompt edge traz o mesmo texto logo após o envio. O intervalo é de 30 segundos, ou dez minutos para um envio enfileirado atrás de um turno. O edge carrega um hash com salt do prompt, nunca o texto em si.

Claude Code e Codex aceitam uma mensagem ou um comando durante um turno. O Collie digita imediatamente, e o harness executa após o turno. Um harness que não pode receber um envio durante seu turno recebe uma retenção de envio. O mesmo vale para uma mensagem que encontra a caixa de entrada ocupada, por exemplo sob um popup, ou em uma tela que muda entre duas leituras do Collie, ou um caractere de teste que falhou e que um Backspace removeu de uma caixa que o Collie leu limpa novamente. Essa mensagem segue após cinco verificações livres ao longo de dez segundos, ou após um turno que o Collie detectar. Um comando ali ainda é recusado, assim como um envio em uma tela que você confirmou com Digite aqui. Um envio em um painel sem perfil nunca é retido. O Collie mantém o texto e mostra um card flutuando na parte inferior da visão do terminal: "Na fila. Envia quando o turno terminar." Em um agente cuja versão o Collie não conseguiu ler, o card informa isso e aponta para collie doctor: o Collie digita em um turno em andamento apenas em uma versão informada pelo agente. O card mostra o texto e um botão Cancelar. O Collie envia após o fim do turno, assim que o painel for lido como livre em duas verificações seguidas, o mais antigo primeiro. Cada envio retido posterior aguarda pelo turno iniciado pelo envio anterior. Se nenhum turno aparecer, ele segue após cinco verificações livres ao longo de dez segundos. Um comando retido no pi, OMP ou Codex envia Enter, e ali o Enter controla o turno. Esse comando aguarda até o turno terminar, assim como qualquer comando retido em um agente cuja versão o Collie não conseguiu ler: duas verificações livres com pelo menos dois segundos de intervalo, ou cinco em dez segundos se o Collie não detectou turno algum. O OMP executa /goal imediatamente durante um turno, então o Collie envia /goal, /goal pause ou /goal resume na hora com Enter. Ele nunca os retém, e eles não esperam atrás de outros envios retidos. Uma mensagem posterior nesse painel aguarda atrás das retidas. Um texto retido dura 30 minutos, um comando retido dura 10 minutos. Depois disso a linha informa que a mensagem não foi enviada e oferece Reenviar. Uma mensagem walky talky também é retida sobre um rascunho, nunca digitada nele, e sua retenção dura 60 minutos (Walky talky). Seu próprio envio sobre um rascunho ainda é recusado, com Anexar e Substituir. Antes de recusar, adicionar ou limpar um rascunho, o Collie digita um caractere de teste e o remove para provar que a caixa aceita teclas; quando a caixa na tela não aceita teclas, o envio é recusado e nada é apagado. Foque esse painel no desktop ou redimensione-o para que o agente redesenhe a tela, depois envie novamente. Alguns comandos nunca esperam, e o Collie os recusa durante um turno. No Claude Code estes são /clear, /exit, /quit, /logout, /resume, /branch e toda linha !. No Codex estes são /quit, /exit, /new, /resume, /logout e toda linha !. No Hermes estes são /exit, /quit, /clear, /new, /resume e toda linha !. Um envio retido sobrevive ao reinício do Collie. Cancelar funciona até o envio começar a sair, e apenas nos painéis desta própria máquina. Com dois ou mais envios retidos, o card mostra uma contagem e o primeiro texto, e Mostrar tudo lista cada envio com seu próprio Cancelar. O Collie mantém o texto retido em disco em texto puro, em um arquivo que apenas o seu usuário pode ler (modo 0600). Ele apaga o texto quando o envio sai e, no máximo, uma hora após o fim da retenção.

O Collie coloca cada edge em um painel. O edge indica o processo do agente e o painel dele (HERDR_PANE_ID, TMUX_PANE ou ZELLIJ_PANE_ID). O Collie descarta um edge que não indica nenhum painel, indica dois painéis ou indica um processo inexistente. O log da bridge exibe então uma linha surface.edge.dropped. Ele exibe no máximo uma linha por motivo e processo a cada minuto. Um edge com mais de 30 segundos, ou um arquivo que não seja um edge, é contabilizado, mas nunca registrado no log.

Quais bridges recebem os edges

Cada bridge que aceita hook edges lista a si mesma em ~/.local/state/collie/hook-targets/ na inicialização. Com XDG_STATE_HOME definido, a pasta é $XDG_STATE_HOME/collie/hook-targets/. Uma bridge remove seu arquivo ao parar normalmente. Uma bridge em execução grava seu arquivo novamente em dois segundos se ele desaparecer. O hook grava cada edge em todas as bridges listadas cujo processo ainda esteja em execução. Ele apaga o arquivo de uma bridge inexistente. Sem nenhuma bridge listada, o hook grava no diretório de estado padrão. Um COLLIE_STATE_DIR no próprio ambiente do agente sempre recebe os edges também.

As informações do painel

As informações do painel no celular mostram se um painel envia hook edges:

• —
  Hooks: ativos significa que o agente naquele painel envia hook edges.
• —
  Hooks: ativos, retém permissões significa que os hooks do agente também retêm permissões para o celular. Consulte Permissões retidas para o celular.
• —
  Hooks: nenhum significa que o Collie não tem nenhum hook edge daquele painel. Os hooks não estão instalados ou o agente não enviou nenhum evento desde a instalação. O Claude Code 2.1.301 detecta novos hooks enquanto executa. Reinicie uma versão mais antiga do Claude.

Uma bridge mantém os painéis ativos ao longo de sua própria reinicialização. A linha permanece "live" após o reinício de uma bridge.

Uma instalação de uma versão anterior do Collie não envia edge para uma caixa de diálogo de permissão. O collie hooks status a exibe como parcial. Execute collie hooks install claude novamente para atualizá-la no local.

Permissões retidas para o celular

$ collie hooks install claude --hold-permissions

Isso adiciona mais um hook, no PermissionRequest do Claude. Quando o Claude solicita uma permissão, o hook retém a solicitação e aguarda o seu toque. O celular exibe a solicitação em forma de card. Um toque em Sim ou Não retorna ao Claude por meio do hook. O Collie não envia nenhuma tecla ao painel para isso. A instalação precisa do Claude Code 2.0.45 ou posterior, a primeira versão com este hook. Ele recusa versões anteriores.

• —
  O hook encontra cada bridge em execução da mesma forma que os hook edges. Ele lê hook-targets/ e faz a retenção com todas as bridges ativas. A primeira resposta prevalece. Os outros celulares informam "Another Collie answered".
• —
  O terminal de mesa continua funcionando. Responda à caixa de diálogo no terminal, e o card no celular mostrará "The desk answered first". O Collie não processa nenhum toque após isso.
• —
  Apenas Yes e No passam pelo hook. Uma opção como "não perguntar novamente" permanece como resposta de tela. O Collie recusa esse toque em um card retido.
• —
  Uma solicitação retida tem um limite de tempo de 290 segundos. Após isso, a caixa de diálogo permanece na tela e se torna um card comum com um novo identificador. Um toque antigo nunca vira teclas.
• —
  Sem bridge, sem retenção. Sem nenhuma bridge escutando, ou em qualquer erro, o hook não imprime nada. O Claude exibe sua própria caixa de diálogo como antes. O hook nunca responde por conta própria.
• —
  O card exibe a entrada apresentada. Esse é o comando, o caminho do arquivo ou outra entrada de texto chave. Ele adiciona os argumentos arriscados do Bash e o texto completo que uma gravação insere em um arquivo. O Collie descarta caracteres que ocultam ou invertem o texto. A entrada exibida tem limite de 1000 caracteres, incluindo o texto gravado. O Collie nunca retém uma solicitação mais longa: o card não pode exibir tudo, portanto a caixa de diálogo na tela responde. Quando a entrada tem mais linhas do que a caixa exibe, o card indica isso.
• —
  Uma requisição retida é dona apenas da caixa de diálogo que exibe essa mesma requisição. O cabeçalho da caixa de diálogo deve indicar a ferramenta da solicitação. Ele deve conter "from the ... agent" exatamente quando um subagente solicitar, e informar o mesmo tipo de subagente. Cada linha da entrada deve aparecer na caixa de diálogo, na ordem. Quando duas solicitações retidas se ajustam a uma caixa de diálogo, nenhuma assume o controle dela. Qualquer outra caixa de diálogo mantém seu próprio card no celular. A solicitação aguarda então no card de retenção correspondente, e somente um toque daquele card responde. O card não aceita toques nos primeiros 400 ms após a exibição de uma nova solicitação. Se você responder à outra caixa de diálogo usando as teclas e o Claude finalizar o hook, o card de retenção informará que as teclas a responderam.
• —
  A requisição de um subagente não mostra nenhum diálogo enquanto o hook a retém. Isso vale para o Claude Code 2.1.301. O card de retenção passa a ser a única forma de vê-la, então ele mostra a ferramenta e a entrada exibida.
• —
  Uma requisição em segundo plano aguarda até o limite de retenção, mesmo sem nenhum celular observando. Então o Collie libera o hook, e o Claude mostra a caixa de diálogo na tela. O Claude 2.1.301 não a recusa.
• —
  Perguntas e planos continuam sendo cards de tela. AskUserQuestion e ExitPlanMode nunca são retidos.

O socket é <stateDir>/hold/sock. A pasta dele usa o modo 0700 e o socket usa o modo 0600, portanto outro usuário não consegue conectar. Antes de conectar, o hook verifica se o socket, a pasta dele e o diretório de estado pertencem a você. Ele também verifica se ninguém mais pode escrever nas duas pastas. O bridge só aceita requisições de processos que ele próprio posiciona em um painel. Ele descarta qualquer outra requisição com uma linha surface.hold.dropped. O hook e as configurações não carregam tokens. Cada card carrega um hash da ferramenta, da entrada exibida e dos rótulos. Um toque com outro hash libera o hook sem resposta.

As informações do painel dizem "holds permissions" quando as configurações que o Claude lê retêm o hook. O Collie lê as configurações do usuário, os dois arquivos de configuração do projeto e as configurações gerenciadas. disableAllHooks desativa a retenção, assim como allowManagedHooksOnly no arquivo gerenciado.

Execute collie hooks install claude sem a flag para retirar a retenção novamente. collie doctor informa em quantos arquivos de configuração os hooks retêm permissões.

Nota. Beacons e hook edges não fornecem um canal de controle. Eles apenas alteram o que o Collie exibe e quando ele lê um painel. Eles não podem enviar texto, injetar toques de tecla, renomear painéis, fechar sessões ou burlar controles de acesso. O modelo de ameaça e os campos omitidos estão documentados em ADR 0024. A retenção de permissão é o único canal de controle. Um toque no celular se torna a resposta do Claude para uma permissão. Quatro proteções garantem isso. O socket pertence apenas a você (modo 0600 em uma pasta 0700), e o hook verifica isso antes de se conectar. O bridge responde apenas a um processo que ele próprio posiciona em um painel. O toque deve carregar o hash da ferramenta, da entrada exibida e dos rótulos que o card exibiu. A resposta é sempre apenas o toque de uma pessoa: o Collie nunca permite ou nega por conta própria.

Codex

O Codex tem um hook externo, seu comando notify. O Collie pode usá-lo para um hook edge quando um turno do Codex termina:

$ collie hooks install codex
$ collie hooks status
/home/you/.codex/config.toml: installed

A instalação escreve uma linha no topo de $CODEX_HOME/config.toml (~/.codex/config.toml quando CODEX_HOME não está definido). A linha fica após os comentários no topo do arquivo:

notify = ["/home/you/.local/bin/collie", "beacon", "emit", "codex"]

O Codex executa apenas um comando de notificação. Se a sua configuração já apontar um, o Collie o mantém no lugar e a instalação é interrompida com uma mensagem. Se o Collie não conseguir ler o arquivo como TOML, a instalação é interrompida e indica a linha. O Collie mantém uma cópia do arquivo antes da primeira alteração. collie hooks uninstall codex restaura os bytes exatos de antes da instalação. Se a instalação criou o arquivo, a desinstalação o remove. Um Codex já aberto pode não ver a nova linha até ser reiniciado.

O Codex envia um evento, agent-turn-complete, ao final de cada turno. O Collie o registra como um stop edge, e a leitura de tela seguinte decide se o painel está livre. Os limites:

• —
  O Codex não envia nenhum evento para caixas de diálogo de aprovação ou para novos prompts. Apenas a tela mostra uma caixa de diálogo, e um envio do celular nunca aparece como Confirmed em um painel do Codex.
• —
  O Codex 0.163.0 executa o comando de notificação a partir de um auxiliar em segundo plano (codex app-server). O Collie localiza a janela do Codex em /proc com o mesmo CODEX_HOME e a pasta do evento. Isso funciona apenas no Linux.
• —
  Duas janelas do Codex na mesma pasta em um mesmo CODEX_HOME não recebem edge. O Collie não consegue diferenciá-las. Seus painéis ainda são atualizados a partir da tela, como ocorre sem o hook.
• —
  O Codex também executa um turno oculto curto para nomear uma nova tarefa. Esse turno envia mais um stop edge, então o painel recebe mais uma leitura de tela.

O Collie pressiona Tab para mensagens do Codex. Durante um turno, o Codex a enfileira. No Codex, o Tab envia uma mensagem em uma caixa ociosa e a enfileira durante um turno. Portanto, Tab é a tecla correta em ambos os estados. Enter direciona um turno em andamento, então o Collie nunca pressiona Enter para uma mensagem. Um texto que começa com / ou ! é um comando. Ele exige Enter em uma caixa ociosa, pois Tab completaria um comando / ali. Durante um turno, ele exige Tab, e o Codex o enfileira como uma mensagem. O Codex executa um texto ! como um comando shell. O comprovante indica queued apenas quando o Codex exibe a linha enfileirada com o texto.

O Collie responde a uma aprovação do Codex com uma única tecla: o dígito da opção, y, ou Escape. Apenas o prompt de confiança do Codex 0.156 navega. Nele, o Collie pressiona as teclas de seta, lê o ponteiro de volta e então pressiona Enter. Uma caixa de diálogo de pergunta do Codex também aceita uma única tecla, o dígito da opção. No Codex 0.163.0, o dígito responde imediatamente. Na última pergunta, ele envia todas as respostas.

Perfis de harness

O Collie verifica a caixa de entrada de um agente antes de enviar uma mensagem a partir do celular. Um arquivo de perfil descreve essa caixa para um agente. Ele indica onde a caixa começa e termina. Ele indica a aparência de um rascunho, qual tecla envia e qual texto o agente exibe para uma colagem longa. Uma shell simples e um agente sem perfil continuam aceitando envios. O Collie não consegue ler a caixa de entrada deles, portanto digita o texto e pressiona Enter sem verificação, uma linha por vez. Apenas uma solicitação de senha nas últimas linhas interrompe o processo: o Collie não digita nada ali, e o celular oferece Digitar.

Um comando, como /model, sempre vai com Enter. Um envio com sondagem digita um caractere extra primeiro. O Collie verifica se o caractere cai na caixa e depois o remove.

• —
  O OpenCode desenha sua caixa como uma coluna de ┃ linhas, fechada por uma linha ╹▀▀▀. O Collie encontra a caixa por essas linhas. Uma mensagem enviada para um turno em execução aguarda na transcrição com um emblema QUEUED. Uma quebra de linha entra como Ctrl+J. O Collie recusa uma mensagem mais longa do que a caixa pode exibir, porque não consegue lê-la de volta.

• —
  O pi desenha sua caixa entre duas réguas sem marca de prompt. O Collie a encontra pelo par de réguas e pela linha de status que o pi desenha abaixo dela. Um diálogo do pi abre entre as mesmas duas réguas. Portanto, o Collie lê as dicas de teclas e a lista a partir da régua superior para baixo. No pi, Enter direciona um turno em execução, mas Alt+Enter envia em uma caixa ociosa e enfileira em um turno. Portanto, o Collie envia com Alt+Enter, e com Ctrl+Q no Windows. O pi mostra uma mensagem enfileirada como uma linha Follow-up: acima da caixa. Uma caixa com mais de 30 linhas de altura não é lida como caixa. A tela é lida como desconhecida, e o envio precisa do seu toque.

• —
  OMP permite escolher o estilo da borda de sua caixa, de modo que o Collie reconhece cinco deles. Um é a caixa aberta com uma linha de status no topo. Outros são um par de réguas, uma régua sem régua inferior, um par com o meio vazio e uma caixa sem borda. O Collie remove a dica que o OMP desenha na extremidade direita da linha de prompt. No OMP, Enter controla um turno em execução, mas Ctrl+Q envia em uma caixa ociosa e enfileira em um turno. Portanto, o Collie envia com Ctrl+Q. O OMP lista uma mensagem enfileirada em um bloco After yield acima da caixa. O OMP pode exibir uma complementação esmaecida após seu texto. Um envio que encontra uma para antes da tecla de envio e deixa o texto na caixa. Na caixa aberta, o OMP mostra no máximo 17 linhas de uma mensagem longa, as últimas. O Collie então compara essas linhas com o final do que digitou, e o recibo confirma isso. Substituir recusa um rascunho que preenche essas 17 linhas, porque o Collie não consegue ver seu início. Nada é apagado.

• —
  O Grok desenha uma caixa arredondada com uma linha de prompt ❯ e uma linha de dicas de teclas abaixo dela. Um rascunho alto mostra uma barra de rolagem na borda direita da caixa. Essa tela é lida como ilegível, portanto o envio precisa do seu toque. Uma lista de modelos abre acima da caixa e conta como parte da caixa. O painel nunca é lido como livre enquanto a lista estiver visível.

• —
  O Antigravity (agy) desenha sua caixa como uma régua, uma linha > e uma régua, com um rodapé ? for shortcuts. O turno mostra uma linha de carregamento com ... acima da caixa e esc to cancel abaixo dela. O Herdr nomeia esse agente como agy ou antigravity. O Collie registra ambos sob agy.

• —
  O Muse desenha sua caixa como uma régua que pode conter um rótulo, uma linha ❯ e uma régua. Uma caixa vazia mostra uma dica cinza, e o Collie lê essa dica como ausência de texto. Uma paleta de comandos aberta sob a caixa aparece como seu rascunho. A lista de tarefas em segundo plano sob a caixa é lida como desconhecida, e o envio precisa do seu toque. Um turno em execução mostra uma linha com um temporizador e esc to interrupt.

• —
  Hermes (o CLI clássico; hermes --tui não é lido) desenha sua caixa como uma linha, uma linha ❯ e uma linha. Abaixo de 64 colunas, ele não desenha a linha abaixo da caixa. Um perfil nomeado exibe seu nome antes de ❯. Quebras de linha entram como Alt+Enter: Ctrl+J envia a mensagem quando display.cli_multiline_shortcuts está desativado. A caixa exibe no máximo oito linhas. Mensagens mais longas não podem ser relidas; portanto, o envio para antes do Enter. Submit faz o envio, e o celular não consegue confirmar se ela foi enviada. O Hermes pode exibir o restante de uma mensagem anterior em cinza após o seu texto. Esse envio também para antes do Enter, e Submit envia apenas o que você digitou. O seletor de modelos e a paleta de comandos abrem sobre o transcript, e o painel nunca é lido como livre sob eles.

• —
  Hermes durante um turno inicia sua linha com ☤, e o Collie detecta o turno a partir dessa marca. O comportamento do Enter é definido pelo próprio Hermes; por isso, o Collie nunca o pressiona durante um turno. Um envio durante o turno é retido e liberado quando o turno termina. Se um turno iniciar enquanto o Collie digita, o envio para antes do Enter e o texto permanece na caixa.

• —
  Perguntas do Hermes: a resposta digitada para uma pergunta abre uma linha ✎, e um envio a partir do celular a responde. Uma mensagem retida nunca entra nessa linha. Ela aguarda o encerramento da pergunta e depois segue como mensagem normal. Enquanto uma mensagem retida aguarda, novos envios se juntam a ela; cancele a mensagem retida para responder a partir do celular.

• —
  Cursor CLI (cursor-agent) desenha sua caixa como uma linha ▄, uma linha → e uma linha ▀. Uma caixa vazia mostra uma dica em cinza, "Plan, search, build anything" ou "Add a follow-up", e o Collie interpreta essa dica como ausência de texto. ! transforma a caixa em um prompt de shell com sua própria dica. O Collie lê essa dica como texto; assim, nenhuma mensagem entra em modo shell. Um turno em execução exibe uma linha com spinner, como Running, acima da caixa e ctrl+c to stop na extremidade direita da linha →. O Collie remove essa dica. Pressionar Enter durante um turno enfileira a mensagem em uma caixa follow-ups acima da caixa de entrada. A caixa exibe no máximo seis linhas e rola rascunhos mais longos. O Collie não consegue reler mensagens mais altas; portanto, ele deixa o texto digitado na caixa e não pressiona Enter. As caixas de diálogo (aprovação de comandos, perguntas, confirmação de confiança na pasta) substituem a caixa, fazendo com que a tela seja lida como ilegível. Envios testados em tempo real foram aprovados em 2026.10.14 e 2026.10.16.

• —
  Kiro desenha sua caixa sob uma régua: uma barra de status, a pasta, uma linha em branco e uma linha de prompt ›. O Collie só digita quando esse quadro inteiro está na tela. Uma nova linha entra como Ctrl+J. Enquanto um turno executa, a linha de prompt mostra Kiro is working. No Kiro, Enter então direciona o texto para esse turno. O Collie não pressiona Enter durante um turno em execução. Ctrl+S alterna o Kiro entre direcionar e enfileirar, então o Collie não define uma tecla de fila. Assim, o Collie retém um envio enquanto o Kiro está ocupado e o envia quando a caixa indica livre. O perfil dele foi verificado apenas no Herdr, não no tmux ou zellij.

Grok, Antigravity e Muse não estão instalados no host de build. Os perfis deles se baseiam em telas salvas de cada agente. Nenhuma mensagem ao vivo foi enviada a eles por meio de um perfil, então o Collie testa cada envio nesses casos. Ninguém mediu o que o Enter faz durante um turno para eles. Por isso, o Collie recusa um envio enquanto a tela mostra o turno em execução e não digita nada. Onde um harness não desenha nenhum sinal de execução, o Collie não consegue identificar, e o agente decide o que o Enter faz. OpenCode e OMP passaram envios ao vivo em uma versão acima da verificada. O Collie testa cada envio neles até que um envio passe dentro do intervalo verificado. Hermes (a CLI clássica) passou envios ao vivo na 0.22.2, dentro do seu intervalo, apenas no Herdr. A TUI Ink (hermes --tui, ou uma configuração que a inicia) ainda não é lida; toque em Digite aqui para enviar. O teste não foi executado em cada diálogo do Hermes, então o Collie testa cada envio lá também.

Uma versão acima da verificada ainda funciona, e o recibo diz provisional.

Direcionar ou enfileirar

Enquanto um agente trabalha, um envio do telefone pode esperar o turno ou entrar nele. Um simples toque em Enviar enfileira seu texto para depois do turno. Isso vale para todos os agentes. O Collie nunca direciona um turno por acidente.

Um direcionamento é uma escolha sua, feita para um único envio. Segure o botão Enviar e toque em Direcionar. O agente lê a linha após a chamada de ferramenta atual, no mesmo turno. A linha aparece apenas enquanto o agente trabalha e somente em um agente que tem uma tecla de direcionamento no seu perfil, por exemplo pi, Codex e OMP hoje. Uma breve dica sob a caixa diz que um toque enfileira e segurar direciona. O Codex interpreta um texto seguido imediatamente por Enter como uma colagem, então o Collie espera um segundo após o texto antes de pressionar a tecla de direcionamento.

O comprovante informa o que aconteceu:

• —
  Direcionado. O agente recebeu a linha no turno em execução. O Collie viu o agente desenhá-la.
• —
  Enfileirado em vez disso. O agente guardou a linha para depois do turno, mesmo com o pedido de direcionar. Nada foi perdido.
• —
  Digitado, não enviado. O texto está na caixa e a tecla de direcionamento não o enviou. Toque em Enviar ou limpe a caixa.
• —
  Indisponível neste painel. O agente não tem tecla de direcionamento no perfil, o Collie não confia na versão dele com um turno em execução ou o texto é um comando. Nada foi enviado. Envie sem Direcionar.
• —
  Apenas uma pessoa no telefone pode direcionar. Um direcionamento de qualquer outra origem é recusado.

Se o turno terminar enquanto o Collie digita, a linha vai como um envio normal. O Collie não retém um direcionamento. Um direcionamento longo pode terminar sem um sinal claro. O comprovante então informa que o Collie não sabe, e o texto não é enviado novamente.

A mensagem de um agente para outro agente (Walky talky) nunca direciona. Ela sempre aguarda o turno.