Configuração

Por padrão, o Collie responde apenas a um dispositivo pareado com collie pair. Um dispositivo pareado tem controle total; portanto, qualquer pessoa na sua tailnet que consiga acessar a URL ainda precisará de um telefone pareado primeiro. Sem COLLIE_TRUSTED_USER, a bridge exibe um aviso de TRUSTED_USER, pois qualquer login na tailnet pode acessar a tela de pareamento. Restrinja o acesso ainda mais:

# in your .env
COLLIE_TRUSTED_USER=you@example.com           # your tailnet login — Collie rejects anyone else
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net    # only behind your OWN proxy; on a tailnet `collie
                                              # start` discovers this for you

O arquivo de configuração

Todas as configurações do Collie podem ser definidas em um arquivo TOML. Gere um com todas as opções e seus valores padrão:

collie config init

Isso grava ~/.collie/config.toml, a própria declaração da máquina, e imprime o caminho. Todas as chaves nele estão comentadas, portanto o arquivo gerado não altera nada: descomente uma chave e reinicie. Em vez disso, execute collie config init --instance para gravar config.toml ao lado de .env, o que substitui o arquivo da máquina para esta instância.

O arquivo de instância prevalece chave por chave, nunca arquivo por arquivo: uma chave ausente nele mantém o valor do arquivo da máquina. Não existe config.<instance>.toml, porque em uma instalação gerenciada pelo Herdr o diretório de configuração já é por instância, e em uma instalação binária ele é ~/.config/collie. Portanto, um segundo Collie em um mesmo host coloca suas próprias configurações em seu próprio diretório de configuração; consulte docs/deployment.md → Vários Collies em um único host. Um .collie/ dentro de um diretório de projeto não é lido.

Três verbos acionam o arquivo:

1. 01
   collie config init grava um arquivo comentado com todas as configurações e seus padrões.
2. 02
   collie config check valida os dois arquivos que seriam lidos, ou um arquivo que você indicar.
3. 03
   collie config show imprime ambos os caminhos e todas as configurações com seus respectivos valores e origens.

A precedência segue o padrão, depois ~/.collie/config.toml, depois <config-dir>/config.toml e então o ambiente do processo, que inclui seu .env. collie config show mostra o vencedor para cada chave de uma só vez, de modo que "por que meu intervalo de sondagem ainda é 1500" é respondido em uma linha.

Uma chave corrompida nunca interrompe o bridge. Uma chave desconhecida ou um tipo incorreto é um problema que o collie config check imprime e o collie doctor relata, e apenas essa chave volta para o que o ambiente define. Todas as outras chaves no arquivo continuam sendo aplicadas.

O Collie lê config.toml apenas durante a inicialização. Execute collie restart após modificá-lo.

Nota. Um arquivo contendo [push] vapid_private ou [stt] stt_key é restrito ao modo 600, exatamente como o seu .env. Se o Collie não puder restringi-lo, apenas essas chaves serão descartadas e o collie doctor avisará.

O ambiente ainda prevalece

O Collie carrega a configuração a partir de um arquivo .env em ~/.config/collie. Se o Herdr gerenciar a instalação, a CLI consulta o Herdr para obter o diretório de configuração do plugin (normalmente ~/.config/herdr/plugins/config/herdr.collie). Ambos os caminhos resolvem de forma consistente entre os comandos da CLI, portanto o serviço lê o arquivo inicializado aqui:

mkdir -p ~/.config/collie && cp .env.example ~/.config/collie/.env

# on a Herdr-managed install, seed Herdr's plugin config dir instead:
cp .env.example "$(herdr plugin config-dir herdr.collie)/.env"

Os caminhos abaixo usam ~/.config/collie/…. Em uma instalação gerenciada pelo Herdr, substitua esse prefixo por $(herdr plugin config-dir herdr.collie).

O Collie lê .env apenas durante a inicialização. Execute collie restart após modificá-lo.

O arquivo .env.example lista todas as opções, assim como o collie config init --print.

Ele inclui COLLIE_PORT, COLLIE_SERVE_MODE=http (para domínios Headscale ou .internal) e COLLIE_SERVE_PORT (para expor HTTPS em uma porta diferente de :443; consulte docs/deployment.md → Vários Collies em um único host). A CLI lê os parâmetros de serve para configurar tailscale serve, em vez de passá-los para a bridge.

O que cada seção contém

O arquivo de configuração agrupa cada configuração sob um [section]. O nome de ambiente de uma chave é COLLIE_ mais a chave em maiúsculas, de modo que [bridge] poll_ms é COLLIE_POLL_MS.

Os agentes duráveis que um Collie executa ao lado do seu multiplexador não estão em config.toml. Cada um é uma entrada em sources.json, no mesmo diretório de .env (Durable agents). | stt | conversão de voz em texto, ausente até que collie stt setup seja executado |

Para ler o histórico de vários diretórios home de agentes, informe uma lista separada por vírgulas em COLLIE_TRANSCRIPT_ROOT.

docs/deployment.md cobre domínios personalizados e proxies reversos. O Collie aplica uma política de mesma origem, portanto qualquer hostname personalizado ou terminador TLS externo precisa estar explicitamente na allowlist:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Sem essa configuração, a UI carregará como uma página vazia. Consulte Solução de problemas para mais detalhes.

Seus próprios comandos slash

Coloque comandos específicos da máquina, como um plugin do Herdr /fork-in-herdr ou um /deploy personalizado, em commands.toml. Este é um dos seis arquivos de configuração que compartilham o mesmo leitor e padrão de carregamento:

Estes arquivos não são alterados pelo arquivo de configuração. Eles compartilham o diretório da instância config.toml, mantêm seus próprios formatos e seu próprio live reload, e nada os mescla a ele.

Qualquer linha com a flag definida requer uma confirmação em dois toques antes de ser executada. Edições em qualquer um desses arquivos entram em vigor sem reiniciar o serviço. Se o Collie rejeitar uma linha, journalctl --user -u collie -n 20 exibe o número da linha e o erro.

cp commands.toml.example ~/.config/collie/commands.toml

[[commands]]
scope = "omp"                # optional; omit for every pane
command = "/fork-in-herdr"
description = "Fork this conversation into a new herdr tab"

[[commands]]
scope = "claude"
command = "/statusline"
description = "Set the status line"
bar = true
bar_label = "Status"

Um painel que corresponde às suas linhas configuradas exibe apenas essas linhas. A linha mais específica vence, conforme documentado em ADR 0018.

Para verificar, abra um painel e toque em /; suas linhas aparecem na primeira tela.

Colocando um comando na linha de ações

bar = true também coloca a linha na linha de ações, a única linha de botões acima do teclado. Uma linha de barra ainda é uma linha de paleta comum, portanto aparece em ambas as superfícies. bar_label é o texto do botão e usa como padrão o nome do comando sem a barra.

A linha de ações é uma faixa contínua acima do teclado. Os controles do próprio Collie ficam diretamente na faixa: Keys, Type, Quick, Agent e a engrenagem de exibição. Os comandos do próprio harness em execução ficam ao lado deles, em uma seção colorida com a cor da marca do harness, para que você veja de relance quais botões digitam no agent. Arrastar para o lado rola a faixa; nada é descartado.

Cada harness inclui seus próprios botões, nesta ordem:

Codex, Grok e Antigravity não têm o botão Effort, porque o seletor de /model deles também define o esforço de raciocínio. Um /effort avulso no Grok não abre seletor algum.

pi e opencode não têm comando de esforço. O pi mantém esse ajuste dentro de /settings, um modal que o teclado virtual não consegue controlar direito, e o opencode alterna suas variantes em uma tecla.

O opencode chama dois botões do seu próprio jeito: Model envia /models e Resume envia /sessions. O Compact dele funciona assim que a sessão contém um turno, porque o opencode só oferece /compact a partir desse momento.

O botão Tree do omp fica entre Compact e Resume. Ele abre a própria árvore de sessão do omp no mirror, um seletor que pula para qualquer ponto anterior da sessão. O mesmo comando, /tree, também está na paleta de comandos do omp.

Cada botão de harness envia seu comando diretamente. Model envia /model, e o próprio seletor de modelos do agent assume o controle no painel. O Collie não mantém nenhuma lista de nomes de modelos, porque essa lista pertence ao harness e muda sem aviso. Effort funciona da mesma maneira.

Suas linhas de barra substituem o segmento padrão do harness nos painéis que elas abordam e o mantêm intacto em todos os outros lugares. A paleta Agent é uma superfície separada e uma linha de barra nunca a apaga (ADR 0043).

Um bar_label com mais de 12 caracteres é encurtado e o botão ainda aparece. Um bar que não seja true ou false descarta essa linha específica, da mesma forma que um confirm inválido faz.

A linha envia enquanto o agent está ocupado, da mesma forma que a paleta de comandos. A marca de seleção aparece apenas quando o painel aceitou o texto.

Um botão Switch fica na extremidade direita da faixa e abre o alternador de painéis. Ele exibe apenas o ícone de camadas, atrás de uma linha fina, e não tem texto. Arrastar para cima, em qualquer lugar da faixa, abre o mesmo alternador. Arrastar para o lado rola a faixa.

A marca de agentes à esquerda do botão Arquivos conta os subagentes em execução no painel. Para omp e Gentle Shell, ela conta seus processos em segundo plano apenas enquanto o Chat do painel estiver aberto no celular; a visão Tela não os conta.

Enquanto a caixa de texto contiver texto ou um anexo, um X também fica na extremidade direita da barra, à esquerda do botão Switch. Um toque esvazia a caixa e seu rascunho salvo, sem enviar nada para o painel. O X então se torna Desfazer, o que restaura o texto e os anexos. O Desfazer permanece até sua próxima ação: pressionar uma tecla, adicionar um anexo, enviar, tocar em outro botão da barra ou sair do painel. Rolar a barra o mantém visível.

Canhoto? Defina Configurações → Aparência → Mão como Esquerda. A barra inverte: o botão Switch e o X vão para a extremidade esquerda, ainda acima de Enviar, e Teclas se torna o botão mais à direita, com os demais rolando para a esquerda. Enviar e Anexar vão para a esquerda da caixa de resposta. A configuração é por dispositivo e passa a valer na próxima vez que você abrir um painel.

Para verificar, abra um painel executando Claude Code, Codex, pi ou omp; o segmento colorido fica à direita da linha acima do teclado. Desative esse segmento por dispositivo em Configurações → Aparência → Atalhos do harness; os controles do próprio Collie permanecem.

Parar um turno

Um botão Parar fica no início da barra, antes dos outros botões do Collie, permanecendo visível sem rolagem. Ele aparece para todo agente cujo perfil de harness define uma tecla de parada e fica esmaecido enquanto nada estiver em execução. Ele mantém a posição e o tamanho, evitando que os outros botões se movam ao iniciar ou terminar um turno. Tocar no botão esmaecido não faz nada e não envia nada. Um agente sem tecla de parada não exibe o botão. O Stop não digita nada e não envia mensagens. Ele pressiona a tecla de parada do próprio agente, uma vez, e informa o resultado.

O Stop precisa de dois toques. O primeiro toque arma o botão: o texto muda para Stop? e o botão mantém o tamanho. Toque novamente dentro de quatro segundos para interromper o turno. Um segundo toque imediato, dentro de 0,4 segundos, conta como o mesmo toque e é ignorado. Se você esperar, o desarme ocorre e nada é pressionado. O desarme também ocorre ao abrir outro painel, e o botão fica esmaecido quando o turno termina. Enquanto o segundo toque é processado, o botão não aceita novos toques, evitando que um terceiro toque rápido dispare outro Stop.

A tecla usada para parar um turno é definida pelo harness, e o perfil do harness a armazena. A maioria dos agentes para com Escape, alguns com Ctrl+C e outros exigem Escape duas vezes. O perfil decide isso, não esta página.

Após enviar a tecla, o Collie lê a tela novamente por até três segundos e exibe uma de três mensagens abaixo da caixa:

Se a tecla de parada abriu uma caixa de diálogo, o Collie avisa e indica o cartão correspondente.

Alguns agentes, entre eles o OMP, colocam uma mensagem enfileirada de volta na caixa de entrada quando você interrompe o turno. Quando o Collie a detecta ali logo após o pressionamento, o recibo informa isso, por exemplo "Interrompido. 1 mensagem na fila voltou para o agente como rascunho." No Chat a mensagem vai para um card De volta na caixa. Mensagens que retornaram juntas compartilham um mesmo card.

O card tem dois botões, e ambos leem a caixa novamente primeiro. Enviar envia o rascunho apenas quando o turno estiver ocioso e a caixa contiver exatamente aquele texto. Descartar limpa a caixa apenas quando ela ainda contiver aquele texto; se você a alterou, Descartar remove o card e não pressiona nada. Enquanto o rascunho permanecer, uma nova mensagem é recusada, e a recusa aponta para o card.

O Collie recusa a ação antes de pressionar a tecla quando isso puder causar problemas:

• —
  A dialog is open. O Escape responderia a essa caixa de diálogo. Responda diretamente no cartão dela.
• —
  The box holds your text, and this harness's stop key would clear it. Limpe a caixa, ou use o botão Clear no teclado Keys, e toque em Stop novamente.
• —
  Collie cannot read this pane. Ele não pressiona teclas em uma tela que não consegue ler. Isso também se aplica a telas onde o Collie não consegue verificar se um turno está em execução.
• —
  The turn had already ended. Não havia nada para parar, portanto nada foi pressionado.
• —
  This machine cannot stop from the phone yet. Em um crew, a máquina que executa o painel possui uma versão mais antiga do Collie. Atualize-a antes de parar.

Se nenhuma resposta retornar de uma máquina do crew a tempo, o Collie avisa. O Stop pode ter sido enviado, então verifique o painel antes de tocar em Stop novamente.

O Stop depende sempre do seu toque. Mensagens do walky talky, hooks, a linha de comando e ações na fila nunca o acionam. Em um crew, a máquina que executa o painel pressiona a tecla, lê a tela e envia a confirmação de volta pelo lead.

Um programa que roda como agente durável mantém o Stop que já tinha. Ele interrompe o turno indicado, com seu próprio recibo, e não usa o arm.

Limpar a caixa

O botão Limpar no fim da linha de chips no teclado Keys esvazia a caixa de entrada do harness em um toque, sem arm. O Collie pressiona a tecla delete do próprio harness quantas vezes o texto exigir, lê a caixa novamente e informa em um aviso acima do belt se a caixa está limpa ou por que não foi esvaziada. O botão fica desativado quando a caixa está vazia, uma caixa de diálogo está aberta ou o link está fora do ar; se a caixa não esvaziar, o Collie mantém o conteúdo restante e não pressiona novamente.

Após Limpar, o aviso oferece Restaurar por dois minutos. Um toque digita o texto de volta na caixa, em uma única linha e sem Enter, portanto nada é enviado. Restore desaparece assim que você digita na caixa novamente ou abre outro painel. A bridge mantém o texto limpo na memória com o recibo do Clear, e nunca o grava em log ou no disco.

Seus próprios presets de teclas

Você pode substituir a linha Presets da bandeja Keys em keys.toml, localizado ao lado de commands.toml:

cp keys.toml.example ~/.config/collie/keys.toml

[[keys]]
scope = "claude"             # optional; omit for every pane
label = "Yes"
keys = ["Down", "Enter"]     # several chords go out as one batch

Quando um painel corresponde às suas linhas definidas, ele exibe apenas seus presets em vez dos botões padrão Ctrl C/D/U/R/L/Z (ADR 0018). Essas linhas pertencem a você como operador e chegam a todos os telefones. O teclado acima delas (Esc, as setas, Enter/Tab/Space, os modificadores) não é configurado aqui: cada telefone organiza o seu, consulte a próxima seção.

Os acordes de teclas usam a sintaxe do herdr, não a do tmux:

Para verificar, abra um painel e toque em Keys → Presets para ver os novos botões. Se o Collie rejeitar uma linha, verifique journalctl --user -u collie -n 20 para ver os detalhes do erro.

Seu próprio painel de teclas

Você pode reorganizar o teclado Keys. Abra Teclas e toque no lápis ao lado do rótulo:

1. 01
   Toque no lápis ao lado de Teclas. Uma folha alta se abre sobre o painel.
2. 02
   Arraste uma tecla para outro lugar ou toque nela e use os quatro botões de seta.
3. 03
   Toque em um + tracejado para adicionar uma tecla em uma célula livre, ou selecione uma tecla e toque em Alterar ou Remover.

O teclado é uma grade de 7 colunas. Uma tecla ocupa uma célula e pode ser mais larga (1, 2 ou 3 colunas) e mais alta (1 ou 2 linhas). Selecione uma tecla e toque em Largura ou Altura para redimensioná-la. Ela cresce para a direita e para baixo. Um tamanho que cobriria outra tecla, ou sairia do teclado, fica esmaecido, e tocar nele indica qual tecla está no caminho. O Collie nunca move uma segunda tecla por você. Adicionar linha adiciona uma linha na parte inferior, até o limite de oito. As alterações aparecem no dock imediatamente. O Collie mantém seu teclado neste navegador, portanto um navegador diferente começa com o teclado padrão até que você compartilhe um layout com ele. O padrão é o teclado que você tinha antes, com a barra de espaço ocupando três células e o Enter na ponta esquerda da segunda linha:

Esc    Tab    Shift  Ctrl   Alt    Up     ^C
Enter  Space (3 wide)        Left   Down   Right

Arrastar uma tecla move sua área inteira. Solte-a sobre uma tecla do mesmo tamanho e as duas trocam de lugar. Solte-a sobre qualquer outra coisa que esteja no caminho e o contorno de destino fica cinza e tracejado, uma linha informa qual tecla está no caminho, e a tecla volta à posição original. Um botão de seta pula as teclas no caminho e para no próximo lugar onde a tecla couber; se não houver nenhum, ele permanece desativado.

Uma tecla envia uma combinação de até três modificadores mais uma tecla, por exemplo Ctrl+Alt+Shift+T. Ela também pode enviar uma sequência curta de até quatro etapas, por exemplo Ctrl+B e depois C. Uma sequência é enviada em ordem como uma única chamada. No construtor de teclas, escolha Caractere, Nomeada ou Teclas F para essas opções. Escolha Modificador para criar uma tecla Ctrl, Alt ou Shift persistente como as do teclado padrão: toque uma vez para armar a próxima tecla, toque de novo para mantê-la pressionada, toque uma terceira vez para soltar. Uma tecla modificadora atua sozinha, logo não tem etapas nem nome. Cada tecla segue o mesmo caminho das teclas integradas: ela aguarda enquanto o painel estiver bloqueado ou offline, uma tecla que pode parar um programa (Ctrl+D, Ctrl+Z ou uma sequência com Ctrl+C) pede um segundo toque, e uma tecla que seu multiplexador não pode enviar fica cinza.

Códigos de versões anteriores ainda são importados, com cada tecla ocupando uma célula. Se Esc, Enter ou uma seta não estiverem no seu teclado, uma linha discreta avisa isso, com Restaurar. A predefinição Prefixo (Ctrl+B) envia o prefixo Ctrl+B, adequada para um tmux em execução dentro do painel. A predefinição Navegação tem Home, End, PgUp e PgDn, que o Herdr não pode enviar, por isso ficam cinza em um painel do Herdr (ADR 0092).

Suas próprias respostas rápidas

Você pode personalizar as frases do dock Quick em quick-replies.toml:

cp quick-replies.toml.example ~/.config/collie/quick-replies.toml

[[replies]]
scope = "claude"             # optional; omit for every pane
title = "confirm"
items = ["yes", "no"]        # sent verbatim, one per button

Quando um painel corresponde às suas regras, seus grupos substituem os padrões (ADR 0018). As frases padrão estão em inglês (yes, commit and push, drastically simplify).

Use este arquivo para executar em outros idiomas ou para enviar palavras como approve para harnesses específicos. Definir scope = "shell" tem como alvo painéis de shell padrão, que de outra forma recebem apenas y/n.

Para verificar, abra um painel e toque em Quick para ver seus grupos. Se uma linha falhar ao carregar, journalctl --user -u collie -n 20 exibirá o erro.

Seus próprios inicializadores

Um toque executa um comando que você declarou, em launchers.toml ao lado de keys.toml:

cp launchers.toml.example ~/.config/collie/launchers.toml

[[launchers]]
command = "htop"             # required; the shell line, typed verbatim into the fresh shell
label = "Top"                # optional; defaults to the first word of command
# cwd = "~/dev/collie"       # optional; absent means "here" — see below

O local onde a linha é aberta depende de onde você a inicia, e não da linha em si. A partir do Nova página (Shell e, depois, a linha no seletor Command), Start cria um novo Space nomeado a partir da sua pasta, e o rótulo da linha dá nome à aba. A partir de um painel (a folha do alternador acessada deslizando para cima), um toque abre um novo aba no próprio Space desse painel, ao lado dele, nomeado a partir da linha.

De qualquer forma, a bridge digita o command no shell recém-criado e envia Enter. O comando gerencia seu próprio ciclo de vida: um que se encerra fecha o Space ou a aba junto, e htop permanece até você sair dele.

cwd é onde esse novo Space ou aba é aberto. Defina uma pasta fixa para uma linha (como htop faz acima) e ela terá prioridade onde quer que você toque na linha.

Omita e isso significa "aqui": o dashboard abre no seu diretório home, um painel abre no cwd do próprio painel — uma linha sem cwd acompanha você pelos seus checkouts em vez de abrir sempre na raiz de um.

Este arquivo e as linhas adicionadas de um celular (abaixo) são a allowlist. O POST /api/launch aceita apenas uma command que corresponda exatamente a uma dessas linhas, um id de agente da própria lista da máquina (a máquina digita o comando desse agente por conta própria) ou uma shell comum. As alterações se aplicam imediatamente sem reiniciar, mas uma aba já aberta relê as linhas apenas no próximo carregamento.

Duas chaves opcionais fornecem mais detalhes sobre uma linha para o telefone:

[[launchers]]
command = "claude-danger"
label = "Claude Code, no prompts"
# The agent that reads the row: it is listed under Agent with that agent's mark.
harness = "claude"
# The line skips permission prompts, but an alias hides its flags.
no_prompts = true

Suas linhas aparecem em três lugares:

• —
  Na página New (toque em + Novo no painel). A chave no topo mostra Agente | Shell. Uma linha com harness fica no seletor Agente. Uma linha sem harness fica no seletor Comando, que é o seletor sob Shell.
• —
  Em uma seção Launch no painel. Ela se dobra como Spaces.
• —
  Em uma seção Launch na folha do alternador (deslize para cima a partir de um painel).

Na página New, uma linha sem cwd roda na pasta especificada ali, e uma linha com pasta fixa exibe essa pasta no lugar do campo. Uma linha nunca inicia em uma worktree; escolha um agente ou Shell para isso. Uma linha com pasta fixa a exibe abreviada sob a home; uma linha sem cwd exibe "here" no alternador (o painel já subentende a home, portanto não mostra nada ali). Não declare linhas e nenhuma das seções aparecerá.

Em uma crew (várias máquinas, um lead conectado ao telefone), cada máquina lê sua própria cópia deste arquivo — uma linha é iniciada no dashboard ou painel da máquina em que você tocou, não no lead.

A seleção Agente na página New é a própria lista do Collie: Claude Code, Codex, opencode, pi, omp, Grok, Hermes, Kiro, Muse e Antigravity. O Kiro inicia com as permissões de ferramentas mantidas como você as configurou. Um agente que não está no PATH de login da máquina permanece na lista, desativado, marcado como "not installed". Para outro agente de terminal, declare uma linha para ele como acima: ele aparece na seleção Comando sob Shell, inicia em um painel como qualquer comando, e o Collie não exibe status para ele.

Para verificar, recarregue o dashboard e olhe sob o herd. Se uma linha falhar ao carregar, journalctl --user -u collie -n 20 exibe o erro.

Inicializadores adicionados de um telefone

Um telefone pode adicionar suas próprias linhas em uma máquina. Elas são mantidas na pasta de estado dessa máquina, em launchers-added.json, nunca em launchers.toml, e nunca copiadas para outra máquina.

Na página New, toque em Add your own sob o seletor Agente ou sob o seletor Comando. Isso abre a página /new/add para a máquina escolhida ali. Escolha Agente ou Comando no topo. Um agente tem dois caminhos: uma recipe (um harness, chips de opções e a linha exata que o Collie digitará) e Write a command. Uma linha de comando é sempre escrita à mão. Adicionar retorna à página New com a nova linha selecionada. Abaixo do formulário, Added on this machine lista cada linha adicionada por um telefone ali, com Rename e Remover, além das linhas de launchers.toml com um cadeado e sem ações. How adding works abre uma breve explicação com o caminho de launchers.toml desta máquina e um exemplo de linha que você pode copiar.

[phone]
adds = true          # default true: a phone may add rows built from a recipe
free_text = false    # default false: a phone may also add a line typed by hand
run = true           # default true: a phone may run a one-off command, and run it again from history

Insira a tabela [phone] em qualquer lugar de launchers.toml. Um valor diferente de true ou false é lido como false. O bridge impõe as chaves: uma adição recusada não altera nada, e uma linha desativada por uma chave para de iniciar imediatamente. A linha permanece no arquivo, portanto reativar a chave a restaura.

Uma recipe é um agente com chips de opções da própria tabela do bridge, por exemplo Claude Code e "Skip permission prompts". O telefone envia apenas os ids, e o bridge monta a linha. Cada chip foi lido do próprio --help desse agente:

Uma linha livre, como um alias como claude-danger ou uma htop simples, só é possível com free_text = true. Sem ela, Write a command mostra uma linha desativada, "Desativado em" na máquina, e Adicionar permanece desativado. Com ela, Verificar a linha mostra a linha com cada caractere oculto escrito como seu código (por exemplo ⟨U+200B⟩) antes de Adicionar ser ativado. Ela tem no máximo 200 caracteres, e a bridge recusa caracteres de controle, separadores de linha ou parágrafo e controles bidi nela, tanto quando é adicionada quanto a cada leitura.

Uma máquina mantém no máximo 20 linhas adicionadas. Se uma linha tiver o mesmo conteúdo de uma linha em launchers.toml, a linha em launchers.toml tem precedência. Cada linha adicionada registra o dispositivo pareado que a adicionou. Revogar esse dispositivo remove suas linhas, pelo telefone ou com collie devices revoke, e o log de auditoria registra cada adição, renomeação e remoção.

Atenção. Uma linha que ignora solicitações de permissão exibe um selo "Sem solicitações". Cada dispositivo pergunta uma vez antes de iniciar essa linha pela primeira vez, e mostra o comando, a pasta e a máquina. Defina adds = false para desativar todas as linhas adicionadas pelo telefone em uma máquina.

Como acessar um agente durável (experimental)

Cada agente durável que um Collie executa ao lado do seu terminal é uma entrada em sources.json, gravada por collie durable attach (Durable agents). As três primeiras variáveis abaixo são o formato anterior, para uma instância exclusiva para agentes duráveis (COLLIE_MUX=durable) que gerencia um agente durável, chamado default. Defina o socket ou a URL com seu token, nunca ambos.

Definir ambos, uma URL sem token ou um token sem URL é um erro de configuração: a instância inicia e mostra o agente durável como inacessível com esse motivo. Por https, cada verificação é uma requisição cobrada, portanto o Collie faz verificações a cada 2 s enquanto um telefone monitora e a cada 10 s caso contrário. Durable agents indica o que cada método bloqueia e o que ele não bloqueia.

Starters de um agente durável (experimental)

Um agente durável lista seus starters na página New que você abre a partir dele, sob Nova conversa. Um starter é uma maneira nomeada de iniciar uma conversa, como uma revisão de código. Ele não recebe texto: você toca nele, e o agente durável decide o que iniciar. A nova conversa abre como um painel. Um toque repetido com o mesmo request id abre a mesma conversa e não inicia nada novo, e se o agente durável não responder, Tentar novamente envia o mesmo request id. Um agente durável que não pode ser alcançado não lista starters. Isso é experimental e pode mudar em qualquer versão minor.

Comandos avulsos e seu histórico

Um telefone também pode executar um comando que não é um launcher, uma única vez. O Collie abre um shell na pasta indicada e digita a linha lá, da mesma forma que inicia uma linha de launcher. A linha segue a mesma regra de uma linha livre: no máximo 200 caracteres, e nenhum caractere de controle, separador ou bidi. Um comando avulso nunca inicia em uma nova branch.

Isso fica ativado por padrão, pois um telefone pareado já pode abrir um shell e digitar nele. Defina run = false na tabela [phone] para remover o atalho nessa máquina.

Na página Novo, mude para Shell. O campo de seleção Comando termina então com duas adições: um grupo Recentes, que lista as linhas no histórico dessa máquina, e Digite um comando…. Escolha Digite um comando… e um campo de texto aparece logo abaixo da seleção. Digite a linha e toque em Iniciar (ou na tecla Enter, que exibe Ir). A linha acima de Iniciar informa o que será executado e onde, por exemplo "Executa htop em ~/projects no bluefin". A opção de worktree permanece desativada para uma linha avulsa.

Antes da primeira execução, o Collie pede para a máquina verificar a linha. A verificação não executa nada e não mantém nada. Se a linha contiver uma flag que ignora solicitações de permissão, como --dangerously-skip-permissions, este telefone pergunta uma vez antes de iniciar, assim como em uma linha com o selo "Sem solicitações". Se a linha violar a regra acima, um aviso explica o motivo e nada é executado.

Escolha uma linha de Recentes para executá-la novamente. O campo Pasta é preenchido com a pasta na qual a linha foi executada pela última vez, a menos que você mesmo tenha alterado a pasta. Enquanto uma linha de Recentes estiver selecionada, Remover do histórico e Limpar histórico aparecem abaixo da seleção. Limpar histórico pergunta primeiro. A linha Novamente no topo da página também repete uma execução avulsa. Com run = false, as linhas em Recentes permanecem na lista, mas ficam desativadas, e Digite um comando… desaparece. Uma máquina anterior à versão 1.19.0 não mostra nenhum dos dois.

Cada comando iniciado é mantido na pasta de estado dessa máquina, em commands-recent.json. O arquivo mantém no máximo 12 linhas, da mais recente para a mais antiga, com a pasta onde cada uma foi executada pela última vez. Executar uma linha novamente move-a para o topo. Uma linha que pareça conter um segredo, como TOKEN=abc deploy, uma URL com senha ou uma palavra como token, secret ou password, ainda é executada, mas não é mantida. Você pode remover uma linha ou limpar a lista pelo telefone. Com run = false, a lista ainda é exibida, mas nada nela é iniciado. Em uma crew, cada máquina mantém sua própria lista, e nada é copiado entre máquinas.

A lista não é uma permissão. Iniciar uma linha a partir dela é uma nova execução avulsa, que precisa de um dispositivo pareado, portanto desparear ou revogar um dispositivo deixa a lista como está. O log de auditoria registra a primeira palavra de um comando avulso e seu tamanho, nunca a linha inteira, porque uma linha pode conter um segredo que você digitou.

Suas próprias fontes

A fonte da interface é uma configuração por dispositivo. Sob Configurações → Aparência → Tipografia, você pode escolher entre System, Space Grotesk, Aldrich (o padrão), IBM Plex Sans, Geist e Atkinson Hyperlegible Next. Um tema que define uma tipografia a grava aqui uma vez, quando você escolhe o tema. Você pode adicionar fontes personalizadas em theme.toml, o quarto arquivo de configuração:

cp theme.toml.example ~/.config/collie/theme.toml
mkdir -p ~/.config/collie/fonts
cp departure.woff2 ~/.config/collie/fonts/

[[font]]
family = "Departure Mono"    # the picker's label AND the CSS family
file   = "departure.woff2"   # a bare name inside fonts/, woff2 only
weight = "400 700"           # optional

Fontes personalizadas são adicionadas ao final da lista integrada em vez de substituí-la (ADR 0033), diferentemente do comportamento em commands.toml e nos outros arquivos de configuração. Como fontes não disparam ações, não há nada para sobrescrever.

Elas aparecem abaixo das entradas padrão fornecidas, e cada dispositivo cliente seleciona a sua.

Três comportamentos a observar:

• —
  Deslocamento de layout no primeiro carregamento. Fontes personalizadas não possuem alternativas com métricas ajustadas, o que causa um leve deslocamento de layout durante o carregamento inicial. As fontes integradas evitam isso porque suas alternativas são geradas em tempo de build.
• —
  Atraso no carregamento a frio. Um carregamento a frio busca o arquivo com um pequeno atraso; um cliente em cache renderiza imediatamente.
• —
  Apenas no chrome. A fonte selecionada se aplica apenas ao chrome do Collie. O espelho do terminal, a transcrição e o markdown renderizado mantêm sua própria tipografia.
• —
  Ativo no próximo recarregamento. As alterações não exigem reinicialização, entrando em vigor no próximo recarregamento da página. Configurações inválidas registram erros visíveis via journalctl --user -u collie -n 20.

Suas próprias regras de cache

Use cache-rules.toml para alterar o tempo de vida do cache de prompt que seu provedor mudou.

cp cache-rules.toml.example ~/.config/collie/cache-rules.toml

O Collie inclui uma regra por harness e provedor. O Collie leu cada regra da página de um fornecedor em uma data registrada. Um fornecedor pode alterar esse valor sem aviso prévio. Um gateway, um proxy que fica entre seu agent e o fornecedor, também pode alterá-lo. Use este arquivo para substituir valores até que o Collie lance uma atualização.

[[rule]]
id = "claude.api"
ttl_seconds = 3600
source_url = "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
retrieved = "2026-09-12"
note = "our gateway sends ttl 1h on every request"

O Collie mantém uma linha apenas quando todas as quatro regras são válidas. id deve indicar uma regra incluída no pacote. ttl_seconds deve ser um número inteiro de 1 a 86400. source_url deve ser uma string não vazia. retrieved deve ser analisada como uma data YYYY-MM-DD válida e não deve ser posterior a hoje. Linhas inválidas são descartadas e registradas no log. O restante do arquivo continua em vigor.

Mais duas regras determinam a interpretação de um arquivo. Duas linhas com o mesmo id não geram erro: a linha posterior tem prioridade. Um note definido como uma string vazia descarta a linha inteira; portanto, simplesmente omita o campo.

Uma linha se vincula à regra de nível (tier), aquela cujo nome consta em id. A divisão por modelo sob esse nível acompanha essa regra, de modo que uma única linha abrange todos os modelos desse nível.

Nota. Você pode alterar um número. Você não pode remover a página de origem nem a data de coleta. O catálogo de regras exige ambos os campos.

collie doctor verifica três itens. cache-claims emite um aviso quando ninguém revisa uma regra incluída no pacote há 180 dias. cache-rules lista todas as linhas descartadas e o motivo do descarte. cache-env alerta quando você define ENABLE_PROMPT_CACHING_1H ou FORCE_PROMPT_CACHING_5M no seu shell. A ponte roda como um serviço separado e não consegue ler o ambiente do seu agente. Replique essas variáveis do Claude Code aqui para que a ponte possa lê-las.

Estes são os IDs de regra que você pode escrever.

A contagem regressiva do cache de prompt

Um indicador em cada painel de agente mostra por quanto tempo o cache de prompt desse agente permanece ativo.

Todo harness compatível armazena a conversa atual em cache. Os harnesses cobram tarifas menores enquanto esse cache permanece ativo. O indicador conta o tempo de inatividade desde a última requisição do agente. Ele não monitora a duração total da sessão. Cada nova requisição redefine o temporizador.

A ampulheta do indicador exibe o estado em uma de três cores, e o número ao lado permanece cinza. A ampulheta fica verde enquanto a janela está ampla, vermelha durante o último quarto dela e azul assim que a janela expira ou um turno paga a tarifa cheia. O indicador mostra cold no estado azul e <1m em vez de segundos quando resta menos de um minuto.

Algumas ações descartam o cache enquanto ainda resta tempo: uma alternância do /model para outro modelo, uma alteração de esforço, uma compactação e /reload-plugins --force. A pastilha fica azul assim que o Claude Code grava a ação em sua transcrição, e a folha indica o nome da ação. O opencode relata uma compactação e uma alteração de modelo da mesma forma.

O indicador fica na extremidade direita da segunda linha do cabeçalho do painel, após a área de trabalho do painel. Em uma crew, o nome da máquina fica ao lado dele, na mesma linha. Toque no indicador para ver a regra subjacente: o ID da regra, a página de origem do fornecedor e a data de coleta.

Nota. Os valores são declarações de fornecedores com datas registradas, não medições em tempo real, a menos que marcados como medido. O Claude Code grava as janelas de cache diretamente em sua transcrição, portanto os painéis do Claude geralmente são medidos.

Alguns painéis não mostram nenhum indicador. Isso é esperado. Um painel exibe um indicador somente após o agente concluir um turno. O Collie não faz suposições antes da medição. Um painel não exibe nada se o harness não tiver um adaptador de journal ou se o fornecedor não publicar dados de tempo de vida.

O Collie também pode enviar alertas push para um celular antes que um cache expire. Uma variável controla o intervalo.

Esta configuração controla apenas o alerta por push. Ela não controla quando o chip fica vermelho. O limite para ficar vermelho é fixo em um quarto do TTL de cada regra. O push em si é disparado no que for menor: esta configuração ou metade da vida útil do cache do próprio painel; assim, um cache de cinco minutos (Codex, OpenCode, pi, omp) avisa cerca de dois minutos e meio antes de esfriar, mesmo que isso seja menor que os 300 segundos configurados. Para ativar avisos em painéis específicos ou em todos os painéis, veja voice-and-push.md.

Anexos

O clipe de papel ao lado da caixa de mensagens faz o upload de um arquivo para o host e insere seu caminho na sua mensagem.

# in your .env
COLLIE_MAX_UPLOAD_MB=25              # default 10, floor 1, ceiling 512
COLLIE_UPLOAD_EXTRA_TYPES=rb,ex,zig  # bare extensions, no dot

O Collie salva o arquivo em <state-dir>/uploads com permissões exclusivas para o proprietário e anexa seu caminho absoluto ao seu rascunho. O agente o lê a partir desse caminho, pois um terminal não pode receber um arquivo colado. Os uploads são removidos 48 horas após serem gravados.

Dois tipos de arquivo são aceitos, e eles são verificados de formas diferentes.

Imagens são identificadas pelos seus bytes de assinatura, nunca pelo nome ou pelo tipo declarado: png, jpg, gif e webp. SVG é recusado de propósito, pois é uma marcação que contém scripts e não uma imagem.

Texto é identificado pela extensão, com os bytes atuando como veto: um arquivo cujos primeiros 4 KB contenham um NUL ou um byte de controle perdido é recusado, seja qual for o seu nome. A lista fornecida é md, markdown, txt, json, jsonl, yaml, yml, toml, csv, tsv, log, xml, html, htm, css, js, jsx, mjs, cjs, ts, tsx, py, go, rs, sh, bash, sql, diff e patch.

Nota. COLLIE_UPLOAD_EXTRA_TYPES adiciona apenas tipos de texto. Uma imagem precisa de uma assinatura para comparação, portanto não há formato binário que você possa adicionar desta forma.

Aumentar COLLIE_MAX_UPLOAD_MB aumenta dois outros números juntos. A bridge lê um upload inteiro na memória antes de conseguir medi-lo, logo um limite alto somado a vários uploads simultâneos consumirá essa quantidade de memória. E o limite de body do runtime se aplica a todas as rotas, não apenas à de upload, de modo que um limite alto permite que um body grande chegue a qualquer handler, onde o limite próprio daquele handler o recusará. Nada é excluído antes de 48 horas, portanto o diretório de uploads guarda no máximo o que foi enviado em dois dias. Aumente o número se você precisar, não por padrão.

Em um crew, ambas as configurações são por máquina, e a máquina que armazena o arquivo é a que as aplica. O lead recusa um body grande demais antes de encaminhá-lo, para economizar seu uplink, mas ele o recusa com base no seu próprio número. Defina os mesmos valores em cada membro, ou um peer recusará o que seu lead permitiu passar.

Pastas favoritas e recentes

A página Novo lista as pastas nas quais você iniciou algo antes, permitindo tocar em uma em vez de digitar um caminho.

Abaixo do campo Pasta ficam duas listas para a máquina de destino da inicialização. Recentes armazena as últimas 8 pastas onde algo foi iniciado, da mais recente para a mais antiga. Conta apenas inicializações que funcionaram e especificaram uma pasta, e nunca lista seu diretório home, pois um campo em branco já significa home. A pasta própria de uma nova branch não é adicionada, pois é um novo checkout, não um local para o qual você retorna.

Você também pode digitar um caminho. ~/projects e /srv/www funcionam de forma literal. Um nome sem / ou ~ no início, como projects, é uma pasta sob seu home, como cd projects em um shell recém-aberto, e a linha acima de Iniciar mostra o caminho completo (~/projects) antes de você tocar. Um caminho contendo .. é recusado. A pasta já deve existir na máquina que executa a inicialização e deve ser um diretório. Se não estiver lá, nada é iniciado e um aviso acima de Iniciar diz "There is no folder … on this machine." O Collie verifica apenas quando você toca em Iniciar, nunca enquanto você digita. Em uma crew, a máquina escolhida verifica seu próprio disco.

Um toque em uma linha preenche o campo Pasta e não inicia nada, permitindo que você ainda altere a escolha acima. A estrela ao lado de uma linha a move para Favoritas, até 12, na ordem em que você as favoritou. Um segundo toque na estrela move-a de volta para o topo de Recentes.

Browse fica abaixo das duas listas. Um toque nele lista as subpastas da pasta no campo, ou da home quando o campo estiver vazio. Toque em uma pasta para entrar nela, e o campo acompanha. Acima, ou parte do caminho acima da lista, volta. Uma pasta que é um repositório Git exibe um selo git. Usar esta pasta preenche o campo, como um toque em uma linha de Recentes.

Quando o campo contém um caminho que não existe, como ~/src/plektra-, o Browse abre na pasta existente mais próxima (~/src) e lista apenas os nomes que começam com o restante (plektra-). Assim, digitar no campo refina a lista. Um caminho fora da sua home exibe "Nothing to browse here".

O Browse lê apenas nomes de pastas, sob sua pasta home, com os limites da visualização Files. Ele oculta pastas que começam com ponto, a menos que você digite o ponto, nunca lista .git ou as pastas de configuração e estado do próprio Collie, não segue links para fora da home e exibe no máximo 200 pastas. Ele não cria nada e precisa de um dispositivo emparelhado, assim como o Files.

A lista pertence à máquina, não ao telefone. Cada máquina mantém a sua em folders.json em seu diretório de estado, ~/.local/state/collie/folders.json a menos que COLLIE_STATE_DIR o mova. Todos os dispositivos que você usa veem a mesma lista, e o arquivo aparece apenas após a primeira inicialização em uma pasta ou a primeira estrela. As mesmas listas preenchem Outra pasta sob Nova worktree, onde definem a pasta na qual a pasta própria da branch é colocada.

Em um crew, cada máquina mantém as pastas que existem nela, e a página exibe a lista da máquina que você escolheu. Uma máquina que roda uma versão mais antiga do Collie não possui lista, e a página não exibe nenhuma para ela. O Browse também lista o disco da máquina que você escolheu, e uma máquina mais antiga informa que precisa de atualização.

Mascaramento de segredos

O Collie mascara formatos de segredos conhecidos no texto do painel antes que ele chegue ao seu telefone.

# in your .env; the default is on
COLLIE_REDACT=off

No arquivo de configuração, isto é [access] redact. A máscara mantém a largura do que oculta, preservando o layout do espelho. Ela detecta apenas formatos de alta confiança; os limites estão em Segurança.

Em uma crew, o líder também mascara o texto enviado pelos membros, de acordo com sua própria configuração. O texto de um membro só chega ao seu telefone sem máscara quando o líder e o membro definirem COLLIE_REDACT=off.

Informar um problema

Quando três envios seguidos em um painel falham por um motivo que aponte para o Collie, um card acima da caixa de resposta oferece a opção de relatar. Configurações → Sistema → Oferecer relatório quando o envio falhar desativa o card para esse dispositivo (salvo no navegador, ativado por padrão). A opção Informar um problema no menu do painel e o botão Informar um problema no mesmo card em Configurações ainda abrem o painel deslizante.

Nada sai do celular até você tocar em Abrir no GitHub ou Copiar relatório, e o Collie não armazena token do GitHub. O conteúdo do relatório e como lê-lo antes de enviar estão em Solução de problemas.

Multissessão

Por padrão, uma instância do Collie atende a todas as sessões do Herdr que encontrar.

COLLIE_MULTI_SESSION=on (o padrão) descobre e serve cada sessão nomeada do Herdr sob a raiz da sua configuração, alternável a partir do cabeçalho. Definir COLLIE_MULTI_SESSION=off serve apenas a sessão primária do Herdr. Cada sessão do Herdr descoberta fica acessível pela mesma URL, incluindo sessões privadas ou de sandbox. Segurança lista este comportamento como um ponto de atenção.

Janelas de uso

Os pontos ao lado do modelo mostram seus limites de 5 horas e 7 dias para Claude e Codex, sem configuração adicional.

# turn every source off
COLLIE_ACCOUNT_WINDOWS=0
# turn on opencode and grok too, or name the ones you want
COLLIE_ACCOUNT_WINDOWS=all
COLLIE_ACCOUNT_WINDOWS=claude,codex

O Collie lê seu arquivo de login do Claude nesta máquina e consulta o endpoint de uso da Anthropic, a mesma chamada que o /usage do Claude Code faz; nenhum dado do login é armazenado ou enviado para outro lugar. O Collie consulta apenas enquanto um painel daquele harness estiver aberto, e ignora arquivos de login que outros possam ler (qualquer permissão mais permissiva que 0600) e logins expirados. O Codex não envia token: ele lê seus próprios arquivos.

Um id que o Collie não reconhece é descartado com um aviso, e apenas os ids reconhecidos são ativados, de modo que um erro de digitação nunca ativa uma fonte não informada. No arquivo de configuração, [bridge] account_windows aceita true ou false, uma string com os mesmos formatos, ou uma array como ["claude", "codex"].

Cada fonte lê uma coisa diferente.

• —
  Claude, ativado por padrão. O Collie lê ~/.claude/.credentials.json, ou $CLAUDE_CONFIG_DIR/.credentials.json, e consulta api.anthropic.com.
• —
  Codex, ativado por padrão. O Collie não lê nenhum login e não consulta ninguém. Em um login do ChatGPT, o Codex grava as janelas em seus próprios arquivos de sessão ($CODEX_HOME/sessions, ou ~/.codex/sessions), e o Collie lê o final dos arquivos mais recentes das últimas duas horas. Um Codex com chave de API não possui janelas para exibir.
• —
  OpenCode Go, desativado por padrão. Quando você ativa, o Collie lê a entrada opencode-go do repositório de login do OpenCode (~/.local/share/opencode/auth.json, ou sob $XDG_DATA_HOME) e consulta opencode.ai. Sem a entrada Go, ele não consulta nada.
• —
  Grok, desativado por padrão. Quando você ativa, o Collie lê o login mantido pelo grok login (~/.grok/auth.json, ou sob $GROK_HOME) e consulta cli-chat-proxy.grok.com para obter seus créditos.

Nota. O OpenCode Go e o Grok seguem o formato que outras ferramentas usam para estes endpoints, e nenhuma conta ativa os verificou ainda. Por isso eles ficam desativados até você nomeá-los. pi e OMP não mostram janelas aqui ainda.

collie doctor mostra cada fonte em sua linha account-windows: ativada ou desativada, o arquivo que ela lê e o host que ela consulta. Terminais contém a linha statusLine.

O ponto de contexto não precisa de configuração. Para pi, OMP, Codex e OpenCode, o Collie lê os tokens do último turno no log da sessão. Ele lê a janela do modelo no log do Codex ou na lista de modelos do próprio harness no disco (models-store.json do pi, models.db do OMP, ~/.cache/opencode/models.json do OpenCode). Um modelo ausente nessa lista não recebe o ponto de contexto; o nome do modelo continua visível. A tag também exibe o custo da sessão em dólares após os pontos quando o harness reporta um: Claude Code por meio da linha de status ajustada, pi, OMP e OpenCode pelos logs. O Codex não possui custo, então sua tag não o exibe.

Modo escuro / modo claro

Nota. O Collie segue a aparência do seu celular por padrão.

Para fixá-lo, abra Configurações → Aparência, encontre o card Aparência sob o card Tema e escolha Sistema, Claro ou Escuro. O card Tema escolhe as cores; este card escolhe a metade clara ou escura delas. A configuração é armazenada por dispositivo no navegador, e não na bridge. Seu celular pode permanecer no Dark enquanto um notebook segue o sistema operacional. A preferência persiste entre recarregamentos e reinstalações do PWA no mesmo dispositivo.

O espelhamento do terminal é deliberadamente diferente

O espelho sempre renderiza sobre um fundo escuro. O modo claro inverte o elemento inteiro em vez de recolorir spans individuais.

Os agents emitem códigos de cor absolutos de 24 bits (38;2;r;g;b) ajustados para fundos escuros, que parsers downstream não conseguem remapear com confiabilidade. Renderizada diretamente sobre o branco, a maior parte da saída dos agents cai abaixo de uma taxa de contraste de 3:1. A inversão preserva o contraste pretendido. As medições estão documentadas no ADR 0002.

Esta implementação tem duas consequências práticas:

• —
  Mantenha seus agents configurados para temas escuros. Este é o padrão para Claude Code, codex, opencode e pi. Se um agent usar um tema claro, ele emitirá valores escuro-sobre-claro que se tornam ilegíveis no Collie em ambos os modos. Isso tem origem na saída do agent, não no Collie em si.
• —
  Diffs e linhas destacadas são renderizados como blocos escuros no modo claro. O contraste permanece intacto, mas o peso visual é invertido.

Nota. Instalado no iOS, no modo claro, o texto da barra de status continua branco e pode se misturar ao fundo. O iOS não permite que web apps atualizem esse valor dinamicamente. Execute o Collie diretamente no navegador em vez de como um PWA instalado para evitar essa limitação.

Modo Zen

Nota. O modo Zen vem desativado por padrão.

Ative em Configurações → Dispositivo → Modo Zen (armazenado por dispositivo no navegador). Isso adiciona uma opção Modo Zen ao menu do painel, sob o ⋮ ao lado de Find e History. Toque nela para ocultar todos os elementos da interface do Collie: o cabeçalho, as barras de abas e painéis, a linha de status do agente e as áreas de composição. Apenas o espelho do terminal permanece visível. Um botão flutuante no canto superior direito ou a tecla Escape restaura a interface.

O modo Zen é transitório. A configuração persiste, mas o estado ativo é redefinido quando você troca de painel ou recarrega a página. Os painéis sempre abrem com a moldura padrão.

O espelho do terminal continua a atualização em segundo plano no modo Zen, e os elementos interativos do buffer continuam funcionais. Os botões de prompt e os controles "Carregar anteriores" e "Mostrar histórico completo" permanecem disponíveis porque fazem parte do fluxo de conteúdo, e não da moldura.

Telas grandes

Nota. Em um tablet ou em um Fold aberto, a tela de painéis mostra vários painéis lado a lado. Um telefone segurado na vertical e plano não é alterado.

O layout é ativado para a tela de painéis quando a tela tem pelo menos 600 pixels CSS de largura e pelo menos 480 pixels de altura. Um telefone segurado de lado tem menos de 480 pixels de altura, portanto mantém o layout de telefone. Para desativá-lo, abra Configurações → Aparência → Layout para telas grandes e escolha Desativado. Automático, o padrão, o ativa onde a tela for grande o suficiente. A escolha é salva por dispositivo.

O layout tem três partes.

• —
  A barra lateral. Lista seus painéis, a mesma lista mostrada pelo alternador de painéis. O botão na linha superior o recolhe para uma barra estreita de ícones, e a escolha é mantida neste dispositivo. A marca ColliePWA na linha superior volta para o início. Novo espaço e Configurações ficam na parte inferior.
• —
  A linha de painéis. Cada espaço mantém sua própria linha, e a linha rola lateralmente. Toque em um painel na barra lateral para exibi-lo. Mantenha-o pressionado (clique com o botão direito do mouse) para Abrir aqui, que substitui o painel em que você está, ou Abrir ao lado, que o adiciona ao lado desse painel. Você também pode arrastar um painel para a linha. Remover da visualização remove um painel da linha. O agente continua em execução.
• —
  O cabeçalho do espaço. Contém o nome do espaço, suas abas e um + para uma nova aba. Mantenha uma aba pressionada (clique com o botão direito do mouse) para Rename ou Fechar aba, como no telefone. Fechar a aba em que você trabalha move você para um painel da aba ao lado. Seus dois botões, ou um deslize vertical, movem para o espaço acima ou abaixo.

Cada painel tem uma largura: 1/2, 4/5 ou Cheia da linha. Um painel nunca é mais estreito que 360 pixels, portanto uma largura que o tornaria mais estreito não é oferecida. Quando a linha não pode conter dois painéis nesse tamanho, cada painel fica com largura Cheia e o controle é ocultado. A linha se ajusta ao início de um painel quando você para de rolar, e uma rolagem para o lado nunca volta uma página no navegador. A linha sempre termina com Adicionar um painel. Ele lista os painéis deste espaço que a linha não mostra, cada um com Abrir aqui (o painel se torna o último na linha). Também oferece Novo agente neste espaço, que abre a página Novo na máquina e pasta desse painel e adiciona o agente como uma nova aba deste espaço, ao lado do painel em que você está, e Novo agente em um novo espaço.

Cada painel tem sua própria faixa, exceto quando você segura um dobrável como um notebook (veja abaixo). O painel em que você trabalha tem uma moldura e a caixa de resposta. Um toque na faixa de outro painel atua nesse painel e move você para lá. Toque no painel para mover sem atuar.

O layout é mantido apenas neste dispositivo, e o botão Voltar e os links compartilhados funcionam como antes.

Dobraveis. Em um dobrável segurado semiaberto, o Chrome e o Samsung Internet dividem a tela na dobra. Segurado como um notebook, a conversa fica acima da dobra, e a faixa e uma caixa de resposta mais alta ficam abaixo dela. Apenas o painel em que você trabalha mantém sua faixa, abaixo da dobra. Os outros painéis mostram apenas o Chat. Esta divisão se aplica a qualquer largura, portanto também altera um celular flip semiaberto. O layout volta a ser plano enquanto o teclado estiver aberto. Segurado como um livro, a divisão se aplica a partir de 600 pixels de largura. Com dois painéis, cada metade mostra um painel e a barra lateral se torna a barra estreita de ícones. Com um painel, a barra lateral permanece aberta em uma metade e o painel preenche a outra. Outros navegadores mostram apenas o layout plano.

Navegação entre painéis

Um gesto move você entre painéis e spaces, tanto no celular quanto no layout de tela grande. Esquerda e direita vão para o painel anterior e seguinte do space, na ordem do alternador. Cima e baixo vão para o space anterior e seguinte. No primeiro ou no último painel ou space, o movimento não sai do lugar. Escolha o método em Configurações → Aparência → Navegação entre painéis. A alteração aparece na próxima vez que um painel for aberto.

A caixa mostra o nome do painel para o qual você está se movendo, com o status, o space e a posição dele no space, acima de um mapa dos spaces. Você permanece onde está se levantar o primeiro dedo sem deslizar, se levantá-lo enquanto o segundo dedo ainda estiver na tela ou se colocar um terceiro dedo. Nada sob os seus dedos é tocado quando eles se levantam. Na primeira vez que o gesto é acionado em um dispositivo, um aviso curto acima da barra inferior explica como ele funciona e onde desativá-lo.

O gesto mantém os toques próprios da página. Um único dedo mantido pressionado não faz nada de novo: o toque longo continua selecionando texto e abrindo o menu de contexto. O gesto de pinça continua aplicando zoom, pois um segundo dedo que toca a tela dentro dos primeiros 300 ms conta como pinça. Um dedo que estava rolando a tela, ou que começa na borda esquerda ou direita onde fica o gesto de voltar do próprio celular, nunca inicia o gesto. A partir do momento em que o segundo dedo toca a tela até você levantar o primeiro, a página suspende a seleção e a rolagem, e qualquer seleção feita antes é limpa. A navegação entre painéis funciona apenas por toque, e o mouse não tem efeito aqui. Com o TalkBack ativado, o gesto não deve fazer nada, pois o TalkBack reserva os deslizes com dois dedos para si; o alternador de painéis continua movendo você.

Visualização de chat

Nota. O Chat é a visualização padrão do painel de um agente desde a versão 1.17.0. O terminal está a um toque de distância.

O painel de um agente abre no Chat. O Chat renderiza a conversa do próprio agente em vez do terminal: suas mensagens, as respostas dele, o raciocínio oculto sob uma dobra e um card por etapa. O editor, a barra inferior e o menu do painel continuam onde estavam. Para ler o terminal em vez disso, abra o menu ⋮ do painel e toque em Visualização do terminal. A escolha é uma configuração para o dispositivo inteiro, salva no navegador, e um dispositivo que já escolheu o terminal mantém a preferência. Visualização de chat no mesmo menu volta para o Chat.

Quando você enfileira uma mensagem enquanto o Claude Code trabalha, o Chat a exibe em um card Aguardando envio, e o botão Enviar agora do card envia toda a fila para o turno em andamento de uma só vez. Apenas o Claude Code oferece isso, porque o botão pressiona Ctrl+Enter, a tecla que esse agente define para isso. O botão fica oculto em um dispositivo somente leitura e em uma cópia salva.

A maioria dos outros agentes, incluindo OMP e pi, não grava nada sobre mensagens enfileiradas no log até o término do turno. Para eles, o Chat exibe as mensagens que o próprio Collie enfileirou no mesmo card Aguardando envio, até que o log do agente mostre cada uma como um prompt. Esse card não tem botões. O Collie não pode remover uma mensagem da fila do agente, portanto não há Cancelar: para retirá-la, interrompa o turno.

Quando o Collie não consegue mais determinar para onde foi uma mensagem enfileirada, o card exibe Não confirmado em vez de sumir. Isso ocorre quando o agente fica ocioso com a caixa vazia duas vezes seguidas, ou após 30 minutos sem nenhum turno em execução. O botão Descartar remove o card e não envia nada.

A engrenagem de exibição tem a opção Respostas em stretchtext, desativada por padrão. Com ela ativada, o Chat, o card de resposta completa e o Histórico exibem uma resposta escrita com o plugin cc-stretch em sua forma curta, e um toque em uma frase a expande. Um {{name}} sem barra é exibido como name.

Um detalhe no Chat ainda está incompleto. O Hermes pode remover um turno do log depois que o Collie o leu, por exemplo durante uma compactação. O Chat continua exibindo esse turno até que a sessão seja lida novamente. O terminal nunca passa por esse problema.

O Chat lê o log de sessão do agente, não a tela. Isso significa que um painel só recebe o Chat quando o Collie sabe qual sessão o painel está executando, e o agente precisa informar isso ao multiplexador. O painel em si não consegue descobrir isso.

O OpenClaw não precisa de integração com o Herdr para o Chat. O Herdr não repassa uma sessão do OpenClaw, então o Collie lê o nome da sessão no rodapé de openclaw tui (agent main (main) | session work | …) e abre o banco de dados de sessão daquele agente sob $OPENCLAW_STATE_DIR, ou ~/.openclaw, em modo somente leitura. Defina openclaw_root quando a pasta de estado estiver em outro lugar. O painel deve se reportar ao Herdr como o agente openclaw. O Collie nunca lê o arquivo de configuração do OpenClaw nem seu gateway token.

O Kiro também não precisa de integração com o Herdr: o Herdr define o agente do painel kiro-cli como kiro, e o Collie localiza a sessão do painel pelo lock que o Kiro em execução mantém nele. O Collie lê sessões do Kiro V3, iniciadas com --v3 ou --agent-engine v3, ou com V3 definido como mecanismo nas configurações do próprio Kiro. Sessões V1 ou V2 não têm Chat nem Histórico. Defina kiro_root quando o Kiro mantiver suas sessões em outro local.

herdr integration status mostra quais integrações estão instaladas. Um hook é lido quando o agente inicia, portanto um agente que já estava em execução quando você o instalou precisa ser reiniciado. Oh My Pi é a integração omp, não a pi: são dois agentes com dois hooks e compartilham o mesmo formato de log.

Um novo painel de agente exibe o Chat de imediato, antes de ter qualquer conteúdo para ler, com uma única linha: "Send a message to start". O Codex relata sua sessão apenas após sua primeira mensagem, e o pi grava seu log somente após a primeira resposta; por isso, ambos começam dessa forma. A conversa aparece assim que existir uma.

Um painel volta para o terminal quando ocorre algo que o Chat não consegue exibir: o agente faz uma pergunta a você antes de haver algo para ler, ou o primeiro turno termina e ele ainda não tem sessão, ou não há arquivo de log para leitura. O terminal exibe então uma linha indicando o que está faltando, e a linha ⋮ explica o motivo. Um primeiro turno que roda por um minuto sem nada para ler e nenhum outro sinal também volta para o terminal. Um painel que já estava ocupado quando você o abriu pela primeira vez, sem sessão, exibe o terminal de imediato. Quando a sessão ou o log chega depois, o painel volta para o Chat. O Chat nunca oculta a linha, permitindo distinguir um hook ausente de um recurso não suportado. O collie doctor lista esses painéis sob agent-sessions e indica a linha de integração (integration-<agent>) que corrige cada um. O página de solução de problemas traz as etapas, sob um painel não tem Chat nem Histórico.

Leitura offline

Quando a bridge está inacessível, o celular exibe a última cópia salva, e você pode lê-la, mas não interagir com ela.

O celular mantém duas coisas para cada painel: o último texto do terminal visto e os turnos mais recentes do Chat conforme o Chat os renderizou. Ele nunca armazena a tela bruta do terminal como Chat. Quando você abre o Collie e a bridge não responde em cerca de um segundo e meio, o celular desenha essa cópia salva imediatamente e a substitui pelos dados ao vivo quando a bridge responder.

Uma cópia salva tem uma aparência diferente da tela ao vivo:

• —
  A lista de agentes fica esmaecida, cada status aparece no passado ("estava trabalhando", "precisava de você"), e o cabeçalho exibe em e a hora em que foi salva.
• —
  Um painel do Chat exibe "Saved copy from" e o horário. A bridge ainda retém os turnos mais antigos.
• —
  Botões de prompt, cards e o botão de envio ficam desativados. Um toque na cópia salva não alcança o agente.

A barra de conexão indica uma de três causas:

Uma VPN como o Tailscale mantém o sinalizador de rede do telefone ativo no modo avião, portanto a barra nem sempre consegue distinguir "sem rede" de "a bridge caiu". Ela apenas informa, então, que a bridge não responde.

Com o aplicativo aberto, a barra e a cópia salva aparecem na primeira sondagem que não obtiver resposta. Uma sondagem aguarda no máximo 6 segundos, um segundo a mais do que a bridge espera pelo multiplexador. Um erro de servidor (5xx) passa a contar na segunda ocorrência consecutiva. O conteúdo da tela permanece visível, e a primeira resposta em tempo real restaura a visualização ao vivo.

Logo após você retornar ao aplicativo, a primeira sondagem sem resposta não conta isoladamente. Uma conexão Tailscale pode levar um instante para se restabelecer, portanto o telefone tenta novamente meio segundo depois e exibe a barra apenas se essa nova sondagem também não obtiver resposta.

Manter o chat neste telefone, em Configurações → Dispositivo, define por quanto tempo as mensagens do Chat permanecem no telefone:

O texto do terminal tem tempo de vida próprio de 24 horas, e essa configuração não o altera. Na visualização do terminal, a única cópia offline é esse texto do terminal.

Nota. O telefone mantém apenas o texto que a bridge já mascarou e descarta a cópia de um painel enquanto ele solicita uma senha. O que o telefone mantém lista cada item, seu limite de tamanho e seu tempo de vida.

Alterações

A tela Tela Files mostra o que um agente alterou nos repositórios git do workspace, na seção Alterações. Duas configurações por dispositivo determinam até onde ela busca por repositórios, em Configurações → Dispositivo → Alterações:

Consulte Qual pasta e quais repositórios para entender como a busca funciona.

Idioma

A interface do Collie está disponível em doze idiomas. Configure essa opção em Configurações → Aparência → Idioma.

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文
• —
  Русский
• —
  Italiano
• —
  Français
• —
  Português
• —
  Türkçe

A seleção é salva localmente no navegador por dispositivo. O espelho do terminal não é traduzido: ele exibe a saída bruta do agente, enquanto respostas rápidas, rótulos de menu e legendas de teclas correspondem aos nomes subjacentes da tela ou do teclado.

O título de uma notificação segue a mesma escolha: "claude needs you" chega como "claude 입력 대기" em um dispositivo configurado para coreano. O dispositivo aplica a nova escolha na próxima vez que o Collie for aberto nele; até lá, os títulos continuam no idioma anterior. O corpo abaixo do título é o nome e local do próprio painel, e nunca é traduzido (Web Push).