Configuración

Por defecto, Collie responde únicamente a un dispositivo emparejado con collie pair. Un dispositivo emparejado tiene control total, por lo que cualquiera en su tailnet que pueda acceder a la URL aún necesita primero un teléfono emparejado. Sin COLLIE_TRUSTED_USER, el bridge imprime una advertencia TRUSTED_USER, porque cada inicio de sesión de tailnet puede acceder a la pantalla de emparejamiento. Restrinja el acceso aún más:

# 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

El archivo de configuración

Cada ajuste de Collie puede definirse en un archivo TOML. Genere uno con todos los ajustes y sus valores predeterminados:

collie config init

Eso escribe ~/.collie/config.toml, la declaración propia de la máquina, e imprime la ruta. Cada clave está comentada, por lo que el archivo tal como se genera no altera nada: descomente una clave y reinicie. Ejecute collie config init --instance en su lugar para escribir config.toml junto a .env, lo que anula el archivo de la máquina para esta instancia específica.

El archivo de instancia prevalece clave por clave, nunca archivo por archivo: una clave ausente conserva el valor del archivo de máquina. No hay config.<instance>.toml, porque en una instalación administrada por Herdr el directorio de configuración ya es por instancia, y en una instalación binaria es ~/.config/collie. Por lo tanto, un segundo Collie en un mismo host coloca su propia configuración en su propio directorio de configuración; consulte docs/deployment.md → Varios Collie en un mismo host. No se lee en absoluto un .collie/ dentro del directorio de un proyecto.

Tres verbos controlan el archivo:

1. 01
   collie config init escribe un archivo comentado con cada ajuste y su valor predeterminado.
2. 02
   collie config check valida los dos archivos que se leerían, o el archivo individual que se indique.
3. 03
   collie config show imprime ambas rutas y cada ajuste con su valor y su procedencia.

El orden de precedencia va del valor predeterminado a ~/.collie/config.toml, luego a <config-dir>/config.toml y después al entorno del proceso, que incluye su .env. collie config show indica el origen ganador para cada clave de una sola vez, por lo que la duda de por qué el intervalo de sondeo sigue en 1500 se responde en una sola línea.

Una clave defectuosa nunca detiene el puente. Una clave desconocida o un tipo incorrecto es un problema que collie config check imprime y collie doctor reporta, y solo esa clave recurre a lo definido en el entorno. El resto de las claves del archivo se siguen aplicando.

Collie lee config.toml únicamente durante el inicio. Ejecute collie restart tras modificarlo.

Nota. Un archivo que contiene [push] vapid_private o [stt] stt_key debe tener el modo 600, exactamente igual que su .env. Si Collie no puede restringirlo, solo esas claves se descartan y collie doctor lo indica.

El entorno sigue prevaleciendo

Collie carga la configuración desde un archivo .env en ~/.config/collie. Si Herdr administra la instalación, la CLI consulta a Herdr por el directorio de configuración del plugin (normalmente ~/.config/herdr/plugins/config/herdr.collie). Ambas rutas se resuelven de forma coherente en todos los comandos de la CLI, por lo que el servicio lee el archivo inicializado aquí:

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"

Las rutas siguientes usan ~/.config/collie/…. En una instalación administrada por Herdr, reemplace ese prefijo por $(herdr plugin config-dir herdr.collie).

Collie lee .env únicamente durante el inicio. Ejecute collie restart tras modificarlo.

El archivo .env.example enumera todas las opciones, al igual que collie config init --print.

Incluye COLLIE_PORT, COLLIE_SERVE_MODE=http (para dominios de Headscale o .internal) y COLLIE_SERVE_PORT (para exponer HTTPS en un puerto distinto de :443; consulte docs/deployment.md → Varios Collie en un mismo host). La CLI lee los parámetros de serve para configurar tailscale serve, en lugar de pasarlos al puente.

Contenido de cada sección

El archivo de configuración agrupa cada ajuste bajo una [section]. El nombre de entorno de una clave es COLLIE_ más la clave en mayúsculas, por lo que [bridge] poll_ms es COLLIE_POLL_MS.

Los agentes durables que Collie ejecuta junto a su multiplexor no están en config.toml. Cada uno es una entrada en sources.json, en la misma carpeta que .env (Durable agents). | stt | voz a texto, ausente hasta que collie stt setup se ejecute |

Para leer el historial de múltiples directorios de inicio de agentes, proporcione una lista separada por comas en COLLIE_TRANSCRIPT_ROOT.

docs/deployment.md cubre dominios personalizados y proxies inversos. Collie aplica una política de mismo origen, por lo que cualquier nombre de host personalizado o terminador TLS externo debe incluirse explícitamente en la lista de permitidos:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Sin este ajuste, la interfaz de usuario se cargará como una página vacía. Consulte Resolución de problemas para más detalles.

Comandos de barra propios

Coloque los comandos específicos de la máquina, como un plugin /fork-in-herdr de Herdr o un /deploy personalizado, en commands.toml. Este es uno de los seis archivos de configuración que comparten el mismo lector y patrón de carga:

El archivo de configuración no modifica estos archivos. Comparten el directorio de la instancia config.toml, conservan sus propios formatos y su propia recarga en vivo, y nada los fusiona en él.

Cualquier fila con el indicador activado requiere una confirmación de dos toques antes de ejecutarse. Las modificaciones en cualquiera de estos archivos surten efecto sin reiniciar el servicio. Si Collie rechaza una fila, journalctl --user -u collie -n 20 imprime el número de línea y el error.

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"

Un panel que coincida con sus filas configuradas muestra únicamente esas filas. Prevalece la fila más específica, como se documenta en ADR 0018.

Para verificar, abra un panel y toque /; sus filas aparecerán en la primera pantalla.

Colocar un comando en la fila de acciones

bar = true también sitúa la fila en la fila de acciones, la única fila de botones sobre el teclado. Una fila de barra sigue siendo una fila de paleta ordinaria, por lo que aparece en ambas superficies. bar_label es el texto del botón y su valor predeterminado es el nombre del comando sin su barra diagonal.

La fila de acciones es una cinta, una franja completa sobre el teclado. Los controles propios de Collie se ubican directamente en la franja: Keys, Type, Quick, Agent y el engranaje de pantalla. Los comandos propios del harness en ejecución se sitúan junto a ellos, en una sección con el color distintivo del harness, permitiendo identificar de un vistazo qué botones envían texto al agente. Al arrastrar lateralmente se desplaza la cinta; no se descarta ningún elemento.

Cada harness incluye sus propios botones, en este orden:

Codex, Grok y Antigravity no tienen botón de Effort, porque su selector /model también define el esfuerzo de razonamiento. Un /effort solo en Grok no abre ningún selector.

pi y opencode no tienen comando de esfuerzo. pi mantiene ese ajuste dentro de /settings, un diálogo modal que el panel de teclas no puede controlar de forma útil, y opencode alterna sus variantes mediante una tecla.

opencode nombra dos botones a su manera: Model envía /models y Resume envía /sessions. Su función Compact funciona una vez que la sesión contiene un turno, porque opencode solo ofrece /compact a partir de ese momento.

El botón Tree de omp se ubica entre Compact y Resume. Abre el propio árbol de sesiones de omp en el espejo, un selector que salta a cualquier punto anterior de la sesión. El mismo comando, /tree, también se encuentra en la paleta de comandos de omp.

Cada botón del harness envía su comando sin formato adicional. Model envía /model, y el selector de modelos propio del agente toma el control en el panel. Collie no mantiene una lista de nombres de modelos, ya que dicha lista pertenece al harness y cambia sin previo aviso. Effort funciona del mismo modo.

Las filas de la barra reemplazan el segmento predeterminado del harness para los paneles a los que se dirigen, y lo dejan intacto en los demás. La paleta Agent es una superficie independiente y una fila de la barra nunca la borra (ADR 0043).

Un bar_label de más de 12 caracteres se trunca y el botón sigue mostrándose. Un bar que no sea true ni false descarta esa fila concreta, de la misma manera que lo hace un confirm no válido.

La fila envía comandos mientras el agente está ocupado, al igual que la paleta de comandos. La marca de verificación aparece solo cuando el panel recibe el texto.

El botón Switch se ubica en el extremo derecho de la cinta y abre el selector de paneles. Muestra únicamente la marca de capas, tras una línea fina, y no contiene texto. Al arrastrar hacia arriba en cualquier punto de la cinta se abre el mismo selector. Al arrastrar lateralmente se desplaza la cinta.

La marca de agentes a la izquierda del botón Archivos cuenta los subagentes en ejecución del panel. Para omp y Gentle Shell, cuenta sus tareas en segundo plano solo mientras el Chat del panel está abierto en un teléfono; la vista de Pantalla no las cuenta.

Mientras el cuadro de texto contenga texto o un adjunto, también aparece una X en el extremo derecho de la barra, a la izquierda del botón Switch. Un toque vacía el cuadro y su borrador guardado, sin enviar nada al panel. La X se convierte entonces en Deshacer, lo que restaura el texto y los adjuntos. Deshacer permanece disponible hasta la siguiente acción: pulsar una tecla, añadir un adjunto, enviar, tocar otro botón de la barra o salir del panel. Desplazar la barra lo mantiene.

¿Es zurdo? Establezca Configuración → Apariencia → Mano en Izquierda. La barra se invierte: el botón Switch y la X se mueven a su extremo izquierdo, aún sobre Send, y Keys pasa a ser el botón situado más a la derecha, desplazándose el resto hacia la izquierda. Send y Attach se mueven a la izquierda del cuadro de respuesta. El ajuste es por dispositivo y se aplica la próxima vez que abra un panel.

Para verificar, abra un panel que ejecute Claude Code, Codex, pi u omp; el segmento tintado se sitúa a la derecha de la fila sobre el teclado. Desactive ese segmento por dispositivo en Ajustes → Apariencia → Atajos de harness; los controles propios de Collie permanecen.

Detener un turno

Un botón Detener se sitúa al inicio de la barra, antes de los otros botones de Collie, de modo que queda visible sin desplazarse. Aparece para cada agente cuyo perfil de harness defina una tecla de detención, y permanece atenuado mientras nada se ejecute. Mantiene su lugar y su tamaño, de modo que los otros botones nunca se mueven cuando un turno empieza o termina. Pulsar el botón atenuado no hace nada ni envía nada. Un agente sin tecla de detención no tiene botón. Stop no escribe nada ni envía mensajes. Presiona la tecla de detención propia del agente, una vez, e informa de lo ocurrido.

Un Stop requiere dos pulsaciones. La primera arma el botón: la palabra cambia a ¿Detener? y el botón conserva su tamaño. Se debe pulsar de nuevo antes de cuatro segundos para detener el turno. Una segunda pulsación inmediata, antes de 0,4 segundos, cuenta como el mismo toque y se ignora. Si se espera, el armado caduca y no se presiona nada. El armado también caduca al abrir otro panel, y el botón se atenúa cuando el turno termina. Mientras la segunda pulsación está en curso, el botón no acepta más toques, por lo que una tercera pulsación rápida no puede presionar un segundo Stop.

La tecla que detiene un turno depende de cada harness, y su perfil la define. La mayoría de los agentes se detienen con Escape, algunos con Ctrl+C y otros requieren Escape dos veces. Lo decide el perfil, no esta página.

Tras enviar la tecla, Collie vuelve a leer la pantalla durante un máximo de tres segundos e indica uno de tres estados bajo el cuadro:

Si la tecla de detención abrió un cuadro de diálogo, Collie lo indica y remite a su tarjeta.

Algunos agentes, entre ellos OMP, devuelven un mensaje en cola a su cuadro de entrada al detener el turno. Si Collie lo detecta allí justo tras pulsar la tecla, el comprobante lo indica, por ejemplo: "Detenido. 1 mensaje en cola ha vuelto al agente como borrador". En Chat, el mensaje pasa a una tarjeta De vuelta en el cuadro. Los mensajes devueltos juntos comparten una misma tarjeta.

La tarjeta tiene dos botones, y ambos leen el cuadro de nuevo primero. Enviar envía el borrador solo cuando el turno está inactivo y el cuadro contiene exactamente ese texto. Descartar vacía el cuadro solo cuando aún contiene ese texto; si se modificó, Descartar retira la tarjeta sin pulsar nada. Mientras el borrador permanezca, se rechaza cualquier mensaje nuevo y el aviso remite a la tarjeta.

Collie rechaza la acción antes de presionar una tecla si hacerlo pudiera causar daños:

• —
  Hay un diálogo abierto. Escape respondería a ese diálogo. Respóndalo en su tarjeta.
• —
  El cuadro contiene texto y la tecla de detención de este harness lo borraría. Vacíe el cuadro o use el botón Clear en el teclado Keys, y luego pulse Stop otra vez.
• —
  Collie no puede leer este panel. No se presiona ninguna tecla en una pantalla que no se puede leer. Esto también incluye pantallas donde Collie no puede determinar si hay un turno en ejecución.
• —
  El turno ya había terminado. No había nada que detener, por lo que no se presionó nada.
• —
  Esta máquina aún no permite detenciones desde el teléfono. En una crew, la máquina que ejecuta el panel tiene una versión más antigua de Collie. Actualícela y luego detenga el turno.

Si una máquina de la crew no responde a tiempo, Collie lo indica. Es posible que el Stop se haya enviado; compruebe el panel antes de pulsar Stop de nuevo.

Un Stop siempre proviene de una pulsación manual. Un mensaje de walky talky, un hook, la línea de comandos y una acción en cola nunca lo presionan. En una crew, la máquina que ejecuta el panel presiona la tecla, lee la pantalla y envía el acuse a través del lead.

Un programa que se ejecuta como durable agent conserva el Stop que ya tenía. Detiene el turno indicado, con su propio comprobante, y no usa el arm.

Vaciar el cuadro

El botón Vaciar al final de la fila de chips en el tablero Keys vacía el cuadro de entrada del harness con un toque, sin arm. Collie presiona la tecla de borrado del propio harness tantas veces como el texto requiera, lee el cuadro nuevamente e informa mediante un aviso sobre la cinta si el cuadro quedó vacío o por qué no fue posible. El botón aparece atenuado cuando el cuadro está vacío, un diálogo está abierto o el enlace está caído; si el cuadro no se vacía, Collie no modifica lo que queda y no vuelve a presionar.

Tras una acción de Clear, el aviso ofrece Restaurar durante dos minutos. Un toque escribe el texto de nuevo en el cuadro, en una sola línea y sin Enter, por lo que no se envía nada. Restore desaparece una vez que se vuelve a escribir en el cuadro o se abre otro panel. El bridge conserva en memoria el texto vaciado junto con el comprobante de Clear, y nunca lo escribe en un registro ni en disco.

Preajustes de teclas propios

Se puede reemplazar la fila Presets de la bandeja Keys en keys.toml, ubicada junto a 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

Cuando un panel coincide con sus filas definidas, muestra únicamente sus ajustes predefinidos en lugar de los botones predeterminados Ctrl C/D/U/R/L/Z (ADR 0018). Estas filas le pertenecen como operador y llegan a cada teléfono. El teclado sobre ellas (Esc, las flechas, Enter/Tab/Space, los modificadores) no se configura aquí: cada teléfono organiza el suyo; consulte la sección siguiente.

Las combinaciones de teclas usan la sintaxis de herdr, no la de tmux:

Para verificar, abra un panel y toque Keys → Presets para ver los nuevos botones. Si Collie rechaza una fila, revise journalctl --user -u collie -n 20 para ver los detalles del error.

Teclado propio

Es posible reorganizar el panel Keys. Abra Teclas y pulse el lápiz junto a la etiqueta:

1. 01
   Pulse el lápiz junto a Teclas. Se abre una hoja vertical sobre el panel.
2. 02
   Arrastre una tecla a otra posición o púlsela y use los cuatro botones de flecha.
3. 03
   Pulse un + discontinuo para añadir una tecla en una celda libre, o seleccione una tecla y pulse Cambiar o Eliminar.

El panel es una cuadrícula de 7 columnas. Una tecla ocupa una celda y puede ser más ancha (1, 2 o 3 columnas) y más alta (1 o 2 filas). Seleccione una tecla y pulse Ancho o Alto para cambiar su tamaño. Crece hacia la derecha y hacia abajo. Si un tamaño cubre otra tecla o sale del panel, se muestra atenuado; al pulsarlo se indica qué tecla interfiere. Collie nunca mueve una segunda tecla automáticamente. Añadir fila añade una fila al final, hasta un máximo de ocho. Los cambios se reflejan en el dock de inmediato. Collie guarda el panel en este navegador, por lo que otro navegador comenzará con el panel predeterminado hasta que se comparta una distribución en él. El valor predeterminado es el panel anterior, con la barra espaciadora de tres celdas de ancho y Enter en el extremo izquierdo de la segunda fila:

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

Al arrastrar una tecla se mueve toda su área. Si se suelta sobre una tecla del mismo tamaño, ambas se intercambian. Si se suelta sobre cualquier otro elemento que interfiera, el contorno de destino se vuelve gris y discontinuo, una línea indica qué tecla interfiere y la tecla regresa a su posición. Un botón de flecha salta las teclas intermedias y se detiene en el siguiente espacio donde quepa la tecla; si no hay ninguno, permanece inactivo.

Una tecla envía una combinación de hasta tres modificadores más una tecla, por ejemplo Ctrl+Alt+Shift+T. También puede enviar una secuencia corta de hasta cuatro pasos, por ejemplo Ctrl+B y luego C. Una secuencia se envía en orden como una sola llamada. En el generador de teclas, elija Carácter, Con nombre o Teclas F para estas opciones. Elija Modificador para crear una tecla fija de Ctrl, Alt o Shift como las del panel predeterminado: púlsela una vez para preparar la siguiente tecla, otra vez para mantenerla presionada y una tercera para liberarla. Una tecla modificadora actúa sola, por lo que no tiene pasos ni nombre. Cada tecla sigue la misma ruta que las integradas: espera mientras el panel esté bloqueado o desconectado, una tecla que pueda detener un programa (Ctrl+D, Ctrl+Z o una secuencia con Ctrl+C) solicita una segunda pulsación, y una tecla que el multiplexor no pueda enviar se muestra en gris.

Los códigos de versiones anteriores siguen siendo compatibles al importar, con cada tecla ocupando una sola celda. Si Esc, Enter o una flecha no están en el panel, una línea discreta lo indica con Restaurar. El ajuste predefinido Prefix (Ctrl+B) envía el prefijo Ctrl+B, por lo que es adecuado para un tmux en ejecución dentro del panel. El ajuste predefinido Navigation incluye Home, End, PgUp y PgDn, que Herdr no puede enviar, por lo que aparecen en gris en un panel de Herdr (ADR 0092).

Respuestas rápidas propias

Se pueden personalizar las frases del dock Quick en 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

Cuando un panel coincide con sus reglas, sus grupos reemplazan a los predeterminados (ADR 0018). Las frases predeterminadas están en inglés (yes, commit and push, drastically simplify).

Utilice este archivo para ejecutar en otros idiomas o para enviar palabras como approve a entornos específicos. Configurar scope = "shell" apunta a paneles de shell estándar, que de lo contrario solo reciben y/n.

Para verificar, abra un panel y toque Quick para ver los grupos. Si una fila no se carga, journalctl --user -u collie -n 20 imprime el error.

Lanzadores propios

Un toque ejecuta un comando declarado, en launchers.toml junto a 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

El lugar donde se abre la fila depende de dónde se inicie, no de la fila en sí. Desde el Nueva página (Shell y luego la fila en la selección Command), Start crea un nuevo Space nombrado a partir de su carpeta, y la etiqueta de la fila da nombre a la pestaña. Desde una panel (la hoja de cambio a la que se accede deslizando hacia arriba), un toque abre un nuevo pestaña en el Space propio de ese panel junto a ella, nombrado a partir de la fila.

En cualquier caso, el puente escribe command en el nuevo shell y envía Enter. El comando gestiona su propio ciclo de vida: uno que se cierra solo se lleva consigo el Space o la pestaña, y htop permanece hasta que se cierre.

cwd es donde se abre ese nuevo Space o pestaña. Si se asigna una carpeta fija a una fila (como hace htop arriba), esta prevalece dondequiera que se toque la fila.

Si se omite, significa "aquí": el panel de control lo abre en el directorio personal, un panel lo abre en el cwd de el propio de ese panel; una fila sin cwd sigue la ubicación actual entre los distintos repositorios en lugar de abrirse siempre en la raíz de uno.

Este archivo y las filas añadidas desde un teléfono (a continuación) conforman la lista de permitidos. POST /api/launch acepta únicamente un command que coincida exactamente con una de esas filas, un identificador de agente de la propia lista del equipo (el equipo escribe directamente el comando de ese agente) o una shell estándar. Los cambios se aplican de inmediato sin reiniciar, pero una pestaña ya abierta vuelve a leer las filas solo en su siguiente carga.

Dos claves opcionales proporcionan al teléfono más información sobre una fila:

[[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

Las filas aparecen en tres lugares:

• —
  En la página New (toque + Nuevo en el panel de control). El selector superior muestra Agente | Shell. Una fila con harness está en el menú desplegable Agente. Una fila sin harness está en el menú desplegable Comando, que es el menú desplegable bajo Shell.
• —
  En una sección Launch en el panel de control. Se pliega como Spaces.
• —
  En una sección Launch en la hoja del conmutador (deslice hacia arriba desde un panel).

En la página New, una fila sin cwd se ejecuta en la carpeta indicada allí, y una fila con una carpeta fija muestra dicha carpeta en lugar del campo. Una fila nunca se inicia en un worktree; elija un agente o Shell para ello. Una fila con una carpeta fija la muestra acortada bajo home; una fila sin cwd indica "here" en el conmutador (el panel de control ya asume home, por lo que no muestra nada allí). Si no se declara ninguna fila, no aparece ninguna de las dos secciones.

En un crew (varias máquinas, un lead orientado al teléfono), cada máquina lee su propia copia de este archivo; una fila se inicia en el panel o dashboard de la máquina donde se pulsó, no en el lead.

El selector Agente en la página New corresponde a la lista propia de Collie: Claude Code, Codex, opencode, pi, omp, Grok, Hermes, Kiro, Muse y Antigravity. Kiro se inicia con los permisos de sus herramientas tal como se hayan configurado. Un agente que no esté en el PATH de inicio de sesión de la máquina permanece en la lista, deshabilitado y marcado como "not installed". Para otro agente de terminal, declare una fila como se indicó anteriormente: aparecerá en el selector Comando bajo Shell, se iniciará en un panel como cualquier comando y Collie no mostrará ningún estado para él.

Para verificar, recargue el panel de control y revise debajo de la manada. Si una fila no se carga, journalctl --user -u collie -n 20 imprime el error.

Lanzadores añadidos desde un teléfono

Un teléfono puede añadir sus propias filas en una máquina. Se guardan en la carpeta de estado de esa máquina, en launchers-added.json, nunca en launchers.toml, y nunca se copian a otra máquina.

En la página New, toque Añadir personalizada bajo el menú desplegable Agente o bajo el menú desplegable Comando. Esto abre la página /new/add para la máquina seleccionada allí. Elija Agente o Comando en la parte superior. Un agente tiene dos modalidades: una receta (un harness, fichas de opciones y la línea exacta que Collie escribirá) y Escribir un comando. Una fila de comando siempre se escribe a mano. Añadir regresa a la página New con la nueva fila seleccionada. Debajo del formulario, Añadido en esta máquina enumera cada fila que un teléfono añadió allí, con Renombrar y Eliminar, y las filas de launchers.toml con un candado y sin acciones. Cómo funciona la adición abre una breve explicación con la ruta de launchers.toml de esta máquina y un ejemplo de fila para 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

Coloque la tabla [phone] en cualquier lugar de launchers.toml. Un valor que no sea true o false se interpreta como false. El puente aplica los selectores: una adición rechazada no cambia nada, y una fila desactivada por un selector deja de iniciarse de inmediato. La fila permanece en el archivo, por lo que reactivar el selector la restablece.

Una receta es un agente más fichas de opciones de la propia tabla del puente, por ejemplo Claude Code y "Skip permission prompts". El teléfono solo envía los identificadores y el puente construye la línea. Cada ficha se leyó desde el propio --help de ese agente:

Una línea libre, como un alias del tipo claude-danger o una htop simple, solo es posible con free_text = true. Sin ella, Escribir un comando muestra una fila desactivada, "Desactivado en" la máquina, y Añadir permanece apagado. Con ella, Comprobar la línea muestra la línea con cada carácter oculto escrito como su código (por ejemplo ⟨U+200B⟩) antes de que Añadir se active. Tiene como máximo 200 caracteres, y el puente rechaza caracteres de control, separadores de línea o de párrafo y controles bidi en ella, tanto al añadirse como cada vez que se lee.

Una máquina conserva como máximo 20 filas añadidas. Si una fila tiene la misma línea que una fila en launchers.toml, prevalece la fila en launchers.toml. Cada fila añadida registra el dispositivo emparejado que la añadió. Al revocar ese dispositivo se eliminan sus filas, desde el teléfono o con collie devices revoke, y el registro de auditoría registra cada adición, cambio de nombre y eliminación.

Precaución. Una fila que omite las solicitudes de permiso lleva una insignia "Sin solicitudes". Cada dispositivo pregunta una vez antes de iniciar esa fila por primera vez y muestra el comando, la carpeta y la máquina. Defina adds = false para desactivar en una máquina cada fila añadida por un teléfono.

Conexión con un agente durable (experimental)

Cada agente durable que Collie ejecuta junto a su terminal es una entrada en sources.json, escrita por collie durable attach (Durable agents). Las primeras tres variables a continuación corresponden al formato anterior, destinado a una instancia exclusiva para agentes durables (COLLIE_MUX=durable) que controla un agente durable llamado default. Defina el socket o la URL con su token, nunca ambos.

Definir ambos, una URL sin token o un token sin URL constituye un error de configuración: la instancia inicia y marca el agente durable como inaccesible por dicho motivo. Mediante https cada sondeo es una solicitud facturada, por lo que Collie sondea cada 2 s mientras un teléfono observa y cada 10 s en caso contrario. Durable agents especifica lo que bloquea cada método y lo que no.

Iniciadores de un agente duradero (experimental)

Un agente duradero enumera sus iniciadores en la página New que se abre desde él, en Nueva conversación. Un iniciador es una forma identificada de comenzar una conversación, como una revisión de código. No admite texto: se pulsa y el agente duradero decide qué iniciar. La nueva conversación se abre como un panel. Una pulsación repetida con el mismo identificador de solicitud abre la misma conversación y no inicia nada nuevo, y si el agente duradero no responde, Reintentar envía el mismo identificador de solicitud. Un agente duradero al que no se puede acceder no enumera iniciadores. Esta función es experimental y puede cambiar en cualquier versión menor.

Comandos únicos y su historial

Un teléfono también puede ejecutar una vez un comando que no sea un lanzador. Collie abre una shell en la carpeta indicada y escribe allí la línea, de la misma manera que inicia una fila de lanzador. La línea sigue la misma regla que una línea libre: como máximo 200 caracteres, y ningún carácter de control, separador o bidi. Un comando único nunca se inicia en una rama nueva.

Esto está activado de forma predeterminada, ya que un teléfono emparejado ya puede abrir una shell y escribir en ella. Defina run = false en la tabla [phone] para eliminar el acceso directo en esa máquina.

En la página New, cambie a Shell. La selección Comando termina entonces con dos adiciones: un grupo Recientes, que lista las líneas del historial de esa máquina, y Escriba un comando…. Elija Escriba un comando… y aparecerá un campo de texto justo debajo de la selección. Escriba la línea y pulse Iniciar (o la tecla de retorno, que muestra Ir). La línea encima de Iniciar indica qué se ejecuta y dónde, por ejemplo "Ejecuta htop en ~/projects en bluefin". El selector de worktree permanece desactivado para una línea única.

Antes de la primera ejecución, Collie solicita a la máquina que compruebe la línea. La comprobación no ejecuta nada ni conserva nada. Si la línea incluye un flag que omite las solicitudes de permiso, como --dangerously-skip-permissions, este teléfono pregunta una vez antes de iniciar, igual que con una fila con la insignia "Sin solicitudes". Si la línea infringe la regla anterior, un aviso indica el motivo y no se ejecuta nada.

Elija una línea de Recientes para ejecutarla de nuevo. El campo Carpeta se completa con la carpeta donde se ejecutó esa línea por última vez, a menos que haya cambiado la carpeta manualmente. Mientras haya una línea seleccionada de Recientes, se muestran Eliminar del historial y Borrar historial debajo de la selección. Borrar historial pregunta primero. La fila De nuevo en la parte superior de la página también repite una ejecución única. Con run = false, las líneas en Recientes permanecen en la lista pero están desactivadas, y Escriba un comando… desaparece. Una máquina anterior a 1.19.0 no muestra ninguna de las dos.

Cada comando iniciado se conserva en la carpeta de estado de esa máquina, en commands-recent.json. El archivo conserva como máximo 12 líneas, las más recientes primero, con la carpeta donde se ejecutó cada una por última vez. Al ejecutar una línea de nuevo se mueve al principio. Una línea que parezca contener un secreto, como TOKEN=abc deploy, una URL con contraseña o una palabra como token, secret o password, se sigue ejecutando pero no se conserva. Puede eliminar una línea, o borrar la lista, desde el teléfono. Con run = false la lista se sigue mostrando, pero no se inicia nada de ella. En un crew, cada máquina conserva su propia lista y no se copia nada entre máquinas.

La lista no constituye un permiso. Iniciar una línea desde ella es una nueva ejecución única que requiere un dispositivo emparejado, por lo que desemparejar o revocar un dispositivo deja la lista tal como está. El registro de auditoría registra la primera palabra de un comando único y su longitud, nunca la línea completa, ya que una línea puede contener un secreto escrito.

Tipografías propias

La fuente de la interfaz es un ajuste por dispositivo. En Ajustes → Apariencia → Tipografía, se puede elegir entre System, Space Grotesk, Aldrich (predeterminada), IBM Plex Sans, Geist y Atkinson Hyperlegible Next. Un tema que especifica una tipografía la escribe aquí una vez, al seleccionar el tema. Se pueden añadir fuentes personalizadas en theme.toml, el cuarto archivo de configuración:

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

Las fuentes personalizadas se añaden al final de la lista integrada en lugar de reemplazarla (ADR 0033), a diferencia del comportamiento en commands.toml y en los otros archivos de configuración. Dado que las fuentes no desencadenan acciones, no hay nada que enmascarar.

Aparecen debajo de las entradas suministradas, y cada dispositivo cliente selecciona la suya.

Tres comportamientos a tener en cuenta:

• —
  Desplazamiento del diseño en la primera carga. Las fuentes personalizadas carecen de alternativas con métricas coincidentes, lo que causa un leve desplazamiento del diseño durante la carga inicial. Las fuentes integradas evitan esto porque sus alternativas se generan en tiempo de compilación.
• —
  Retraso en carga en frío. Una carga en frío descarga el archivo con un breve retraso; un cliente en caché renderiza de inmediato.
• —
  Solo interfaz. La fuente seleccionada se aplica únicamente a la interfaz de Collie. El espejo del terminal, la transcripción y el markdown renderizado conservan su propia tipografía.
• —
  Activo en la siguiente recarga. Los cambios no requieren reinicio y surten efecto en la siguiente recarga de la página. Las configuraciones inválidas registran errores visibles mediante journalctl --user -u collie -n 20.

Reglas de caché propias

Utilice cache-rules.toml para modificar el tiempo de vida de la caché de prompts si su proveedor lo ha cambiado.

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

Collie incluye una regla por harness y proveedor. Collie obtuvo cada regla de la página de un proveedor en una fecha registrada. Un proveedor puede modificar ese valor sin previo aviso. Una pasarela, un proxy situado entre el agente y el proveedor, también puede cambiarlo. Utilice este archivo para anular los valores hasta que Collie publique una actualización.

[[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"

Collie conserva una fila solo cuando se cumplen las cuatro reglas. id debe nombrar una regla incluida. ttl_seconds debe ser un entero de 1 a 86400. source_url debe ser una cadena no vacía. retrieved debe interpretarse como una fecha YYYY-MM-DD válida y no debe ser posterior al día de hoy. Las filas no válidas se descartan y se registran. El resto del archivo se sigue aplicando.

Dos reglas más determinan el significado de un archivo. Dos filas con el mismo id no constituyen un error: prevalece la fila posterior. Un note escrito como una cadena vacía descarta toda la fila; por lo tanto, omita el campo.

Una fila se vincula al nivel de regla que su id nombra. La división por modelo bajo ese nivel se traslada con ella, por lo que una sola fila cubre cada modelo de ese nivel.

Nota. Es posible modificar un número. No se permite eliminar su página de origen ni la fecha de recuperación. El catálogo de reglas exige ambos campos.

collie doctor comprueba tres elementos. cache-claims advierte cuando nadie ha vuelto a verificar una regla incluida en 180 días. cache-rules nombra cada fila descartada y el motivo del descarte. cache-env señala cuando se define ENABLE_PROMPT_CACHING_1H o FORCE_PROMPT_CACHING_5M en el shell. El puente se ejecuta como un servicio independiente y no puede leer el entorno de su agente. Replique estas variables de Claude Code aquí para que el puente pueda leerlas.

Estos son los identificadores de regla que se pueden escribir.

La cuenta regresiva de la caché de instrucciones

Un indicador en cada panel de agente muestra cuánto tiempo permanece activa la caché de instrucciones de ese agente.

Cada entorno compatible almacena en caché la conversación actual. Los entornos aplican tarifas más bajas mientras esa caché permanezca activa. El indicador descuenta el tiempo de inactividad desde la última solicitud del agente. No registra la antigüedad total de la sesión. Cada nueva solicitud reinicia el temporizador.

El reloj de arena del indicador refleja el estado en uno de tres colores, y el número situado a su lado permanece en gris. El reloj de arena es verde mientras la ventana es amplia, rojo durante el último cuarto de esta y azul una vez que la ventana expira o un turno paga la tarifa completa. El indicador muestra cold en el estado azul, y <1m en lugar de segundos cuando queda menos de un minuto.

Algunas acciones descartan la caché mientras aún queda tiempo: un cambio de /model a otro modelo, un cambio de esfuerzo, una compactación y /reload-plugins --force. El chip se vuelve azul tan pronto como Claude Code escribe la acción en su transcripción, y la hoja nombra la acción. opencode informa una compactación y un cambio de modelo de la misma manera.

El indicador se ubica en el extremo derecho de la segunda línea del encabezado del panel, después del espacio de trabajo del panel. En un crew, el nombre de la máquina se sitúa a su lado, en la misma línea. Toque el indicador para ver la regla subyacente: el identificador de la regla, la página de origen del proveedor y la fecha de recuperación.

Nota. Los valores son declaraciones del proveedor con fechas registradas, no mediciones en tiempo real, a menos que se marquen como medido. Claude Code escribe las ventanas de caché directamente en su registro, por lo que los paneles de Claude suelen estar medidos.

Algunos paneles no muestran ningún indicador. Esto es normal. Un panel muestra un indicador solo después de que su agente completa un turno. Collie no hace suposiciones antes de la medición. Un panel no muestra nada si su entorno carece de un adaptador de diario o si su proveedor no publica datos sobre el tiempo de vida.

Collie también puede enviar alertas push a un teléfono antes de que expire una caché. Una variable controla los intervalos de tiempo.

Este ajuste controla únicamente la alerta push. no controla cuándo el indicador pasa a rojo. El umbral rojo se fija en un cuarto del TTL de cada regla. La notificación push se activa con el valor más corto entre este ajuste o la mitad de la vida útil de la caché del propio panel; por lo tanto, una caché de cinco minutos (Codex, OpenCode, pi, omp) advierte unos dos minutos y medio antes de enfriarse, aunque sea inferior a los 300 segundos configurados. Para habilitar advertencias para paneles específicos o para todos los paneles, consulte voice-and-push.md.

Adjuntos

El icono de clip junto al cuadro de mensaje sube un archivo al host y coloca su ruta en el mensaje.

# 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

Collie guarda el archivo en <state-dir>/uploads con permisos exclusivos para el propietario y añade su ruta absoluta al borrador. El agente lo lee desde esa ruta, ya que una terminal no admite pegar archivos. Las subidas se purgan 48 horas después de haberse escrito.

Se aceptan dos tipos de archivos, y se comprueban de manera diferente.

Imágenes se identifican por sus bytes de firma, nunca por su nombre o su tipo declarado: png, jpg, gif y webp. SVG se rechaza deliberadamente, ya que es marcado con capacidad de ejecutar scripts en lugar de una imagen.

Texto se identifica por su extensión, con los bytes como veto: un archivo cuyos primeros 4 KB contengan un byte NUL o de control aislado se rechaza independientemente de su nombre. La lista incluida es 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 y patch.

Nota. COLLIE_UPLOAD_EXTRA_TYPES añade únicamente tipos de texto. Una imagen requiere una firma contra la cual comprobarse, por lo que no hay formatos binarios que se puedan añadir de esta forma.

Aumentar COLLIE_MAX_UPLOAD_MB incrementa otros dos números a la vez. El puente lee una subida completa en memoria antes de poder medirla, por lo que un límite alto junto con varias subidas simultáneas consumirá esa cantidad de memoria. Además, el límite del cuerpo del runtime se aplica a todas las rutas, no solo a la de subida, por lo que un límite alto permite que un cuerpo grande llegue a cualquier controlador, donde el propio límite de ese controlador lo rechazará. No se elimina nada antes de que transcurran sus 48 horas, por lo que el directorio de subidas almacena como máximo lo enviado en dos días. Aumente el número únicamente si lo necesita, no por defecto.

En un crew, ambos ajustes son por máquina, y la máquina que almacena el archivo es la que los aplica. El nodo principal rechaza un cuerpo de tamaño excesivo antes de reenviarlo, para ahorrar enlace de subida, pero lo rechaza según su propio número. Configure los mismos valores en cada miembro, o un par rechazará lo que su nodo principal permitió pasar.

Carpetas favoritas y recientes

La página New lista las carpetas donde inició algo anteriormente, para poder pulsar una en lugar de escribir una ruta.

Debajo del campo Folder se encuentran dos listas correspondientes a la máquina de destino. Recientes contiene las últimas 8 carpetas donde se inició algo, las más recientes primero. Solo contabiliza los inicios correctos que especificaron una carpeta, y nunca lista su directorio home, ya que un campo vacío ya representa home. La carpeta propia de una rama nueva no se añade, ya que es un checkout nuevo y no un lugar al que regresar.

También puede escribir una ruta. ~/projects y /srv/www significan lo que indican. Un nombre sin / o ~ iniciales, como projects, es una carpeta dentro de su home, como cd projects en una shell limpia, y la línea encima de Start muestra la ruta completa (~/projects) antes de pulsar. Se rechaza una ruta que contenga ... La carpeta ya debe existir en la máquina que ejecuta el inicio y debe ser un directorio. Si no existe, no se inicia nada y un aviso encima de Start indica "There is no folder … on this machine." Collie comprueba solo al pulsar Start, nunca mientras se escribe. En un crew, la máquina elegida comprueba su propio disco.

Al pulsar una fila se completa el campo Folder y no se inicia nada, lo que permite cambiar la selección anterior. La estrella junto a una fila la mueve a Favoritos, hasta 12, en el orden en que se marcaron. Al pulsar la estrella por segunda vez vuelve al principio de Recent.

Explorar se ubica debajo de las dos listas. Un toque sobre él muestra las subcarpetas de la carpeta en el campo, o del directorio personal si el campo está vacío. Al tocar una carpeta se ingresa en ella y el campo se actualiza. Arriba, o una parte de la ruta sobre la lista, permite regresar. Una carpeta que sea un repositorio Git incluye una insignia git. Usar esta carpeta completa el campo, al igual que un toque en una fila de Recent.

Cuando el campo contiene una ruta inexistente, como ~/src/plektra-, Browse se abre en la carpeta existente más cercana (~/src) y muestra solo los nombres que comienzan con el resto (plektra-). Así, escribir en el campo reduce la lista. Una ruta fuera del directorio personal muestra "Nothing to browse here".

Browse solo lee nombres de carpetas dentro del directorio personal, con los mismos límites de la vista Files. Oculta carpetas que comienzan con punto salvo que se escriba dicho punto, nunca lista .git ni las carpetas de estado y configuración propias de Collie, no sigue enlaces fuera del directorio personal y muestra un máximo de 200 carpetas. No crea ningún elemento y requiere un dispositivo emparejado, al igual que Files.

La lista pertenece a la máquina, no al teléfono. Cada máquina conserva la suya en folders.json dentro de su directorio de estado, ~/.local/state/collie/folders.json a menos que COLLIE_STATE_DIR lo mueva. Cada dispositivo utilizado ve la misma lista, y el archivo aparece solo tras el primer inicio en una carpeta o la primera estrella. Las mismas listas completan Otra carpeta bajo Nuevo worktree, donde eligen la carpeta contenedora de la carpeta propia de la rama.

En un crew, cada máquina conserva las carpetas existentes en ella, y la página muestra la lista de la máquina seleccionada. Una máquina que ejecuta una versión anterior de Collie carece de lista, por lo que la página no muestra ninguna para ella. Browse también lista el disco de la máquina seleccionada, y una máquina desactualizada indica que requiere una actualización.

Secret masking

Collie enmascara patrones conocidos de secretos en el texto del panel antes de que llegue a su teléfono.

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

En el archivo de configuración esto es [access] redact. La máscara conserva el ancho de lo que oculta, de modo que el diseño del espejo se mantiene. Solo detecta patrones de alta confianza; los límites se detallan en Seguridad.

En un crew, el líder también enmascara el texto que envían sus miembros, según su propia configuración. El texto de un miembro llega a su teléfono sin enmascarar únicamente cuando tanto el líder como ese miembro configuran COLLIE_REDACT=off.

Informar de un problema

Cuando fallan tres envíos consecutivos en un panel por una causa atribuible a Collie, una tarjeta sobre el cuadro de respuesta ofrece informar del error. Ajustes → Sistema → Ofrecer informe si falla el envío desactiva la tarjeta para ese dispositivo (se guarda en el navegador, activa por defecto). La opción Informar de un problema del menú del panel y el botón Informar de un problema de la misma tarjeta en Ajustes siguen abriendo el formulario.

Nada sale del teléfono hasta pulsar Abrir en GitHub o Copiar informe, y Collie no almacena ningún token de GitHub. El contenido del informe y cómo revisarlo antes de enviarlo se describen en Resolución de problemas.

Multisesión

Por defecto, una instancia de Collie atiende todas las sesiones de Herdr que encuentra.

COLLIE_MULTI_SESSION=on (la opción predeterminada) detecta y sirve cada sesión con nombre de Herdr bajo su raíz de configuración, intercambiable desde el encabezado. Establecer COLLIE_MULTI_SESSION=off solo sirve la sesión primaria de Herdr. Cada sesión de Herdr detectada es accesible mediante la misma URL, incluidas las sesiones privadas o de sandbox. Seguridad cataloga este comportamiento como un punto delicado.

Ventanas de uso

Los puntos junto al modelo muestran los límites de 5 horas y 7 días para Claude y Codex, sin necesidad de configuración 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

Collie lee el archivo de inicio de sesión de Claude en esta máquina y consulta el endpoint de uso de Anthropic, la misma llamada que realiza /usage en Claude Code; ningún dato del inicio de sesión se almacena ni se envía a otra parte. Collie consulta únicamente mientras haya un panel de ese harness abierto, y omite archivos de inicio de sesión legibles por otros usuarios (cualquier permiso más permisivo que 0600) o inicios de sesión caducados. Codex no envía ningún token: lee sus propios archivos.

Un id no reconocido por Collie se descarta con una advertencia y solo se activan los ids reconocidos, por lo que un error tipográfico nunca activa una fuente no especificada. En el archivo de configuración, [bridge] account_windows admite true o false, una cadena con las mismas formas, o un arreglo como ["claude", "codex"].

Cada fuente lee un elemento distinto.

• —
  Claude, activo por defecto. Collie lee ~/.claude/.credentials.json, o $CLAUDE_CONFIG_DIR/.credentials.json, y consulta api.anthropic.com.
• —
  Codex, activo por defecto. Collie no lee ningún inicio de sesión ni realiza consultas. En un inicio de sesión de ChatGPT, Codex escribe las ventanas en sus propios archivos de sesión ($CODEX_HOME/sessions, o ~/.codex/sessions), y Collie lee el final de los archivos más recientes de las últimas dos horas. Un Codex que utilice una clave de API no tiene ventanas para mostrar.
• —
  OpenCode Go, inactivo por defecto. Al activarse, Collie lee la entrada opencode-go del almacén de credenciales de OpenCode (~/.local/share/opencode/auth.json, o bajo $XDG_DATA_HOME) y consulta opencode.ai. Sin una entrada de Go, no realiza ninguna consulta.
• —
  Grok, desactivado por defecto. Al activarse, Collie lee el inicio de sesión conservado por grok login (~/.grok/auth.json, o bajo $GROK_HOME) y consulta cli-chat-proxy.grok.com para obtener los créditos.

Nota. OpenCode Go y Grok siguen el formato que otras herramientas usan para estos endpoints, y ninguna cuenta activa los ha verificado todavía. Por eso están desactivados hasta que se configuren. pi y OMP todavía no muestran ventanas aquí.

collie doctor muestra cada origen en su fila account-windows: activado o desactivado, el archivo que lee y el host al que consulta. Terminales contiene la ruta de statusLine.

El punto de contexto no requiere configuración. Para pi, OMP, Codex y OpenCode, Collie lee los tokens del último turno a partir del registro de sesión. Lee la ventana del modelo desde el registro de Codex o desde la lista de modelos del propio harness en disco (models-store.json de pi, models.db de OMP, ~/.cache/opencode/models.json de OpenCode). Un modelo no listado allí no recibe punto de contexto; el nombre del modelo se sigue mostrando. La etiqueta muestra también el coste de la sesión en dólares tras los puntos cuando el harness lo reporta: Claude Code mediante la línea de estado ajustada; pi, OMP y OpenCode a partir de sus registros. Codex no lo incluye, por lo que su etiqueta no muestra coste.

Modo oscuro / modo claro

Nota. Collie sigue la apariencia del teléfono por defecto.

Para fijarlo, abra Configuración → Apariencia, busque la tarjeta Apariencia bajo la tarjeta Tema y elija Sistema, Claro o Oscuro. La tarjeta Tema selecciona los colores; esta tarjeta selecciona la mitad clara o la mitad oscura de ellos. El ajuste se almacena por dispositivo en el navegador en lugar de en el puente. Su teléfono puede permanecer en Dark mientras un portátil sigue la configuración del sistema operativo. La preferencia persiste tras recargas y reinstalaciones de la PWA en el mismo dispositivo.

El espejo del terminal es diferente de forma deliberada

El espejo siempre se renderiza sobre un fondo oscuro. El modo claro invierte todo el elemento en lugar de cambiar el color de cada span por separado.

Los agentes emiten códigos de color absolutos de 24 bits (38;2;r;g;b) ajustados para fondos oscuros, los cuales los analizadores posteriores no pueden reasignar de forma confiable. Renderizada directamente sobre blanco, la mayor parte de la salida del agente cae por debajo de una relación de contraste de 3:1. La inversión conserva el contraste previsto. Las mediciones están documentadas en ADR 0002.

Esta implementación tiene dos consecuencias prácticas:

• —
  Mantenga los agentes configurados con temas oscuros. Este es el valor predeterminado para Claude Code, codex, opencode y pi. Si un agente utiliza un tema claro, emite valores de texto oscuro sobre fondo claro que se vuelven ilegibles en Collie en ambos modos. Esto se debe a la salida del agente y no a Collie.
• —
  Los diffs y las filas resaltadas se renderizan como bloques oscuros en modo claro. El contraste permanece intacto, pero el peso visual se invierte.

Nota. Al instalarse en iOS, en modo claro, el texto de la barra de estado permanece blanco y puede confundirse con el fondo. iOS no permite que las aplicaciones web actualicen este valor de forma dinámica. Ejecute Collie directamente en el navegador en lugar de como PWA instalada para evitar esta limitación.

Modo Zen

Nota. El modo Zen está desactivado de forma predeterminada.

Actívelo en Configuración → Dispositivo → Modo Zen (se almacena por dispositivo en el navegador). Esto añade la opción Modo Zen al menú del panel, bajo el icono ⋮ junto a Find e History. Al pulsarlo, se ocultan todos los elementos de la interfaz de Collie: el encabezado, las barras de pestañas y paneles, la línea de estado del agente y los acoplamientos del compositor. Solo permanece visible el reflejo del terminal. Un botón flotante en la esquina superior derecha o la tecla Escape restaura la interfaz.

El modo Zen es transitorio. La configuración persiste, pero el estado activo se restablece al cambiar de panel o recargar la página. Los paneles siempre se abren con la interfaz estándar.

El reflejo del terminal continúa sondeando en modo Zen y los elementos interactivos del búfer siguen funcionando. Los botones de indicaciones, "Load older" y los controles "Show entire history" permanecen disponibles porque forman parte del flujo de contenido y no de la interfaz.

Pantallas grandes

Nota. En una tableta o en un Fold abierto, la pantalla de paneles muestra varios paneles uno al lado del otro. Un teléfono sostenido en vertical y plano no cambia.

El diseño se activa para la pantalla de paneles cuando la pantalla tiene al menos 600 píxeles CSS de ancho y al menos 480 píxeles de alto. Un teléfono en posición horizontal tiene menos de 480 píxeles de alto, por lo que mantiene el diseño de teléfono. Para desactivarlo, abra Ajustes → Apariencia → Diseño para pantallas grandes y elija Desactivado. Automático, la opción predeterminada, lo activa cuando la pantalla es lo bastante grande. La elección se guarda por dispositivo.

El diseño consta de tres partes.

• —
  La barra lateral. Muestra la lista de paneles, la misma que el selector de paneles. El botón de la fila superior lo pliega en una barra estrecha de iconos, y la preferencia se guarda en este dispositivo. La marca ColliePWA de la fila superior lleva al inicio. Nuevo espacio y Settings se ubican al pie.
• —
  La fila de paneles. Cada espacio mantiene su propia fila, y la fila se desplaza horizontalmente. Toque un panel en la barra lateral para mostrarlo. Manténgalo presionado (clic derecho con un ratón) para Abrir aquí, que reemplaza el panel actual, o Abrir al lado, que lo añade junto a dicho panel. También se puede arrastrar un panel a la fila. Quitar de la vista retira un panel de la fila. El agente sigue ejecutándose.
• —
  El encabezado del espacio. Contiene el nombre del espacio, sus pestañas y un + para una nueva pestaña. Mantenga presionada una pestaña (clic derecho con un ratón) para Renombrar o Cerrar pestaña, igual que en el teléfono. Cerrar la pestaña en la que se trabaja traslada a un panel de la pestaña contigua. Sus dos botones, o un deslizamiento vertical, permiten pasar al espacio superior o inferior.

Cada panel tiene un ancho: 1/2, 4/5 o Completo de la fila. Un panel nunca mide menos de 360 píxeles, por lo que no se ofrece un ancho que lo haga más estrecho. Si la fila no puede alojar dos paneles de ese tamaño, cada panel adopta el ancho Completo y el control se oculta. La fila se ajusta al inicio de un panel al detener el desplazamiento, y el desplazamiento lateral nunca retrocede una página en el navegador. La fila siempre termina con Añadir un panel. Enumera los paneles de este espacio que la fila no muestra, cada uno con Abrir aquí (el panel pasa a ser el último de la fila). También ofrece Nuevo agente en este espacio, que abre la página Nuevo en la máquina y carpeta de ese panel y añade el agente como una nueva pestaña de este espacio, junto al panel en uso, y Nuevo agente en un nuevo espacio.

Cada panel tiene su propia franja, salvo cuando se sostiene un plegable como un portátil (véase más abajo). El panel activo incluye un marco y el cuadro de respuesta. Al pulsar la franja de otro panel se actúa sobre él y la vista se desplaza allí. Pulse sobre el panel para desplazarse sin realizar acciones.

El diseño solo se conserva en este dispositivo, y la función Atrás y los enlaces compartidos funcionan como antes.

Plegables. En un plegable sostenido semiabierto, Chrome y Samsung Internet dividen la pantalla en el pliegue. Sostenido como un portátil, la conversación se mantiene sobre el pliegue, y la franja y un cuadro de respuesta más alto se sitúan debajo. Solo el panel activo conserva su franja, bajo el pliegue. Los demás paneles solo muestran el chat. Esta división se aplica a cualquier ancho, por lo que también modifica los teléfonos tipo concha semiabiertos. El diseño vuelve a ser plano mientras el teclado está abierto. Sostenido como un libro, la división se aplica a partir de 600 píxeles de ancho. Con dos paneles, cada mitad muestra un panel y la barra lateral pasa a ser una barra de iconos. Con un solo panel, la barra lateral permanece abierta en una mitad y el panel ocupa la otra. Los demás navegadores solo muestran el diseño plano.

Navegación entre paneles

Un gesto permite desplazarse entre paneles y espacios, tanto en un teléfono como en la vista de pantalla grande. Izquierda y derecha van al panel anterior y siguiente del espacio, en el orden del selector. Arriba y abajo van al espacio anterior y siguiente. En el primer o último panel o espacio, el movimiento se detiene. Seleccione el método en Ajustes → Apariencia → Navegación entre paneles. El cambio se aplica la próxima vez que se abre un panel.

El cuadro indica el nombre del panel de destino, su estado, su espacio y su posición dentro del espacio, sobre un mapa de los espacios. La posición no cambia si se levanta el primer dedo sin deslizar, si se levanta mientras el segundo dedo sigue apoyado o si se apoya un tercer dedo. No se activa ningún elemento bajo los dedos al levantarlos. La primera vez que se inicia el gesto en un dispositivo, un aviso breve sobre la barra inferior explica cómo funciona y dónde desactivarlo.

El gesto conserva las interacciones táctiles propias de la página. Mantener un solo dedo no produce ninguna acción nueva: una pulsación larga sigue seleccionando texto y abriendo su menú. El gesto de pellizcar sigue aplicando zoom, ya que un segundo dedo que toca la pantalla dentro de los primeros 300 ms cuenta como pellizco. Un dedo que estaba desplazando la pantalla, o que inicia el toque en el borde izquierdo o derecho donde opera el gesto de retroceso del teléfono, nunca inicia el gesto. Desde que el segundo dedo toca la pantalla hasta que se levanta el primero, la página bloquea la selección y el desplazamiento, y se borra cualquier selección previa. La navegación entre paneles funciona solo de forma táctil; el ratón no realiza ninguna acción aquí. Con TalkBack activado, el gesto no realiza ninguna acción, ya que TalkBack reserva los deslizamientos de dos dedos para su propio uso; el selector de paneles sigue permitiendo desplazarse.

Vista de chat

Nota. Chat es la vista predeterminada de un panel de agente desde 1.17.0. La terminal está a un toque de distancia.

Un panel de agente se abre en Chat. Chat muestra la conversación propia del agente en lugar de la terminal: los turnos del usuario, sus respuestas, el razonamiento tras un desplegable y una tarjeta por cada paso. El editor, la barra inferior y el menú del panel permanecen donde estaban. Para ver la terminal en su lugar, abra el menú ⋮ del panel y pulse Vista de terminal. La elección es una configuración única para todo el dispositivo, almacenada en el navegador, y el dispositivo que ya eligió la terminal la conserva. Vista de chat en el mismo menú permite regresar.

Cuando se pone en cola un mensaje mientras Claude Code trabaja, Chat lo muestra en una tarjeta Esperando para enviar, y el botón Enviar ahora de la tarjeta envía toda la cola de una vez al turno en ejecución. Solo Claude Code ofrece esto, ya que el botón pulsa Ctrl+Enter, la tecla que dicho agente define para esta acción. El botón se oculta en un dispositivo de solo lectura y en una copia guardada.

La mayoría de los demás agentes, entre ellos OMP y pi, no escriben nada sobre un mensaje en cola en su registro hasta que termina el turno. Para ellos, Chat muestra los mensajes que el propio Collie puso en cola en la misma tarjeta Esperando para enviar, hasta que el registro del agente muestra cada uno como instrucción. Esa tarjeta no tiene botones. Collie no puede retirar un mensaje de la cola del agente, por lo que no existe Cancelar: para recuperarlo, detenga el turno.

Cuando Collie ya no puede determinar adónde fue un mensaje en cola, la tarjeta muestra No confirmado en lugar de desaparecer. Esto ocurre cuando el agente permanece inactivo con un cuadro vacío dos veces consecutivas, o tras 30 minutos sin un turno en ejecución. Su botón Descartar retira la tarjeta y no envía nada.

El icono de configuración de pantalla incluye el interruptor Respuestas con texto expandible, desactivado por defecto. Al activarlo, Chat, la tarjeta de respuesta completa e Historial muestran las respuestas redactadas con el complemento cc-stretch en su formato abreviado, y una pulsación en una frase la despliega. Un {{name}} sin barra se muestra como name.

Se sabe que un elemento de Chat está incompleto. Hermes puede eliminar un turno de su registro después de que Collie lo haya leído, por ejemplo al compactar. Chat continúa mostrando ese turno hasta que la sesión se lea de nuevo. La terminal nunca presenta este problema.

Chat lee el registro de sesión del agente, no la pantalla. Esto significa que un panel solo obtiene Chat cuando Collie sabe qué sesión está ejecutando el panel, y el agente debe informarlo al multiplexor. El panel por sí mismo no puede deducir esto.

OpenClaw no necesita integración con Herdr para Chat. Herdr no reenvía una sesión de OpenClaw, por lo que Collie lee el nombre de la sesión en el pie de página de openclaw tui (agent main (main) | session work | …) y abre la base de datos de sesiones de ese agente bajo $OPENCLAW_STATE_DIR, o ~/.openclaw, en modo de solo lectura. Configure openclaw_root si la carpeta de estado se encuentra en otra ubicación. El panel debe notificarse a Herdr como agente openclaw. Collie nunca lee el archivo de configuración de OpenClaw ni su token de gateway.

Kiro tampoco requiere integración con Herdr: Herdr asigna al panel kiro-cli el agente kiro, y Collie localiza la sesión del panel mediante el bloqueo que el proceso activo de Kiro mantiene en él. Collie lee sesiones de Kiro V3, iniciadas con --v3 o --agent-engine v3, o configuradas con V3 como motor en los propios ajustes de Kiro. Una sesión V1 o V2 no dispone de Chat ni de Historial. Defina kiro_root si Kiro almacena sus sesiones en otra ubicación.

herdr integration status muestra qué integraciones están instaladas. Un hook se lee cuando el agente inicia, por lo que un agente que ya estaba en ejecución al instalarlo necesita reiniciarse. Oh My Pi es la integración de omp, no la de pi: son dos agentes con dos hooks y comparten un formato de registro.

Un nuevo panel de agente muestra Chat de inmediato, antes de tener algo que leer, con una sola línea: "Send a message to start". Codex reporta su sesión solo tras el primer mensaje del usuario, y pi escribe su registro solo tras su primera respuesta, por lo que ambos inician de esta manera. La conversación aparece en cuanto existe.

Un panel recurre a la terminal cuando ocurre algo que Chat no puede mostrar: el agente hace una pregunta antes de que haya algo para leer, o su primer turno termina y aún no tiene sesión, o no hay archivo de registro para leer. La terminal muestra entonces una línea indicando lo que falta, y la fila ⋮ indica el motivo. Un primer turno que se ejecuta durante un minuto sin nada para leer y sin otra señal también recurre a la terminal. Un panel que ya estaba ocupado al abrirse por primera vez, sin sesión, muestra la terminal de inmediato. Cuando la sesión o el registro llegan más tarde, el panel vuelve a Chat. Chat nunca oculta la fila, de modo que es posible distinguir la falta de un hook de la falta de una función. collie doctor lista esos paneles bajo agent-sessions e indica la línea de integración (integration-<agent>) que soluciona cada uno. El página de solución de problemas contiene los pasos, bajo un panel no tiene Chat ni Historial.

Lectura sin conexión

Cuando el puente está inaccesible, el teléfono muestra la última copia que guardó, y es posible leerla pero no interactuar con ella.

El teléfono conserva dos elementos por cada panel: el último texto de terminal recibido y los turnos de Chat más recientes tal como Chat los representó. Nunca conserva la pantalla de terminal sin procesar como Chat. Al abrir Collie y no recibir respuesta del puente en aproximadamente un segundo y medio, el teléfono muestra esta copia guardada de inmediato y la reemplaza con datos en vivo en cuanto el puente responde.

Una copia guardada difiere visualmente de una pantalla en vivo:

• —
  La lista de agentes aparece atenuada, cada estado se muestra en tiempo pasado ("trabajaba", "le necesitaba"), y el encabezado muestra a partir de y la hora en que se guardó.
• —
  Un panel de Chat muestra "Saved copy from" y la hora. El puente todavía conserva los turnos anteriores.
• —
  Los botones de prompt, las tarjetas y el botón de envío están desactivados. Pulsar en una copia guardada no comunica con el agente.

La barra de conexión indica una de tres causas:

Una VPN como Tailscale mantiene activo el indicador de red del teléfono en modo avión, por lo que la barra no siempre puede distinguir entre "sin red" y "el bridge está caído". En ese caso, solo indica que el bridge no responde.

Con la aplicación abierta, la barra y la copia guardada aparecen en el primer sondeo que no obtiene respuesta. Un sondeo espera como máximo 6 segundos, un segundo más de lo que el bridge espera al multiplexor. Un error del servidor (5xx) cuenta al segundo consecutivo. El contenido de la pantalla permanece y la primera respuesta en directo restablece la vista en directo.

Justo al volver a la aplicación, el primer sondeo que no obtiene respuesta no cuenta por sí solo. Un enlace de Tailscale puede tardar un momento en restablecerse, por lo que el teléfono vuelve a consultar medio segundo después y muestra la barra solo si ese sondeo tampoco obtiene respuesta.

Guardar el chat en este teléfono, en Ajustes → Dispositivo, define cuánto tiempo se conservan los turnos de Chat en el teléfono:

El texto del terminal tiene una vigencia propia de 24 horas que este ajuste no modifica. En la vista de terminal, la única copia sin conexión es dicho texto del terminal.

Nota. El teléfono solo conserva el texto que el bridge ya ha enmascarado y descarta la copia de un panel mientras este solicita una contraseña. Lo que conserva el teléfono enumera cada elemento, su límite de tamaño y su tiempo de vida.

Cambios

El Pantalla Files muestra los cambios introducidos por un agente en los repositorios git de su espacio de trabajo, bajo su segmento Cambios. Dos ajustes por dispositivo determinan el alcance de búsqueda de repositorios, en Configuración → Dispositivo → Cambios:

Consulte Qué carpeta y qué repositorios para ver cómo funciona la búsqueda.

Idioma

La interfaz de Collie está disponible en doce idiomas. Esto se configura en Configuración → Apariencia → Idioma.

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

La selección se guarda localmente en el navegador por dispositivo. El reflejo del terminal permanece sin traducir: muestra la salida sin procesar del agente, mientras que las respuestas rápidas, las etiquetas de menú y los nombres de las teclas coinciden con los nombres subyacentes de la pantalla o del teclado.

El título de una notificación sigue la misma elección: "claude needs you" llega como "claude 입력 대기" en un dispositivo configurado en coreano. El dispositivo adopta la nueva opción la próxima vez que se abra Collie en él; hasta entonces, los títulos permanecen en el idioma anterior. El cuerpo debajo del título es el nombre y la ubicación propios del panel, y nunca se traduce (Web Push).