Configuración

Herdr funciona sin fichero de configuración. Añade uno cuando quieras atajos, temas, disposiciones de la barra lateral, notificaciones o comportamientos avanzados personalizados.

La referencia de configuración lista todos los ajustes y atajos, con tipos, valores por defecto y valores admitidos. Esta página cubre la puesta en marcha, las recetas habituales y las estructuras de configuración que necesitan más explicación que una fila de referencia.

Fichero de configuración

Herdr lee la configuración de:

Linux y macOS: ~/.config/herdr/config.toml
Windows:       %APPDATA%\herdr\config.toml

Ejecuta herdr --help para ver la ruta de configuración resuelta en tu sistema.

Imprime la configuración por defecto completa:

herdr --default-config

Guárdala como tu configuración si quieres un punto de partida completo:

herdr --default-config > ~/.config/herdr/config.toml

Si un valor de configuración no es válido, Herdr recurre a un valor seguro por defecto y muestra un aviso al arrancar.

Herdr muestra la configuración inicial cuando onboarding falta o es true. Continuar desde la configuración inicial escribe onboarding = false y abre los ajustes en la pestaña de integraciones. Pon onboarding = false para saltarte ese flujo después de configurar.

onboarding = false

Recargar la configuración

Recarga un servidor en marcha después de editar config.toml:

herdr server reload-config

También puedes abrir el menú global de Herdr y elegir reload config.

La recarga aplica la mayoría de los ajustes de la interfaz sin reiniciar los paneles. Los ajustes que solo se leen al arrancar siguen necesitando un reinicio.

Los temas, las disposiciones de la barra lateral, el comportamiento al copiar y demás ajustes de presentación salen de la configuración local del cliente, también cuando estás viendo una máquina SSH. Los valores por defecto de los paneles, los worktrees, las integraciones y los comandos personalizados pertenecen al servidor donde corren los paneles. La acción reload config de la interfaz recarga tanto los ajustes locales del cliente como la configuración del servidor seleccionado. Los atajos locales también se recargan; --remote-keybindings server usa en su lugar los atajos del servidor seleccionado.

Tamaño de terminal sin cliente

Cuando no hay ningún cliente conectado, el servidor usa una terminal virtual de 120×40 para la disposición y para los paneles nuevos. Cambia ese valor de respaldo para la orquestación sin interfaz con:

[server]
headless_cols = 160
headless_rows = 50

Con un cliente conectado, todas las pestañas siguen su tamaño. Con varios clientes, cada pestaña que se está viendo sigue al cliente que la enfocó, seleccionó o usó más recientemente. Cuando se desconectan todos menos uno, todas las pestañas vuelven de inmediato al tamaño del cliente que queda. Cuando no queda ninguno, los PTY de los paneles existentes conservan su último tamaño y la disposición sin cliente usa el valor de respaldo configurado.

Valores por defecto de la terminal

Define el ejecutable que Herdr usa para los paneles interactivos nuevos:

[terminal]
default_shell = "nu"

Si falta o está vacío, Herdr usa $SHELL y después /bin/sh en Unix. En Windows usa pwsh.exe (PowerShell 7) si se resuelve en el PATH, y si no, el powershell.exe incluido (Windows PowerShell 5.1). Es un nombre o ruta de ejecutable, no una línea de comandos. Los paneles existentes conservan su shell actual hasta que se recrean. Las cadenas de los atajos de comandos personalizados se ejecutan con /bin/sh -c para comandos de panel y /bin/sh -lc para comandos en segundo plano en Unix; en Windows, con cmd.exe /d /c.

Define cómo arranca Herdr los shells interactivos de los paneles nuevos:

[terminal]
shell_mode = "auto"

shell_mode = "auto" arranca shells de inicio de sesión (login) en macOS, para que la configuración del PATH exclusiva de esos shells, como /usr/libexec/path_helper y la inicialización de Homebrew, se ejecute en los paneles nuevos. En las demás plataformas conserva el comportamiento anterior sin login. Usa "login" para forzar el arranque como shell de inicio de sesión o "non_login" para forzar lo contrario. Los paneles de comando, los atajos de comandos personalizados en segundo plano y los lanzamientos explícitos por argv conservan sus vías de ejecución.

Define la política de directorio de trabajo para paneles, pestañas y espacios de trabajo nuevos:

[terminal]
new_cwd = "follow"

new_cwd = "follow" mantiene el comportamiento por defecto: hereda el del panel o espacio de trabajo de origen. Cuando no hay espacio de trabajo de origen, Herdr arranca en $HOME. Usa "home" para arrancar siempre en $HOME, "current" para usar el directorio del proceso de Herdr, o una ruta fija como "~/Projects". Los valores explícitos de --cwd de la CLI o la API de socket siguen teniendo prioridad.

Worktrees

Define el directorio raíz que Herdr usa para las copias de trabajo (worktrees) de Git creadas desde la barra lateral:

[worktrees]
directory = "~/.herdr/worktrees"

Herdr crea las copias en <directorio>/<repo>/<slug-de-la-rama>. Para copias al lado del repositorio, apunta a un directorio como ~/Projects/herdr-worktrees. Los valores relativos se resuelven a una ruta absoluta cuando la aplicación aplica la configuración.

Las acciones de worktree están en las filas de espacios de trabajo de Git. New worktree crea una copia. Si la rama introducida ya existe en local, la usa; si no, la crea. Después abre la copia como un espacio de trabajo nuevo y lo agrupa bajo el espacio de trabajo de origen. Open worktree... lista las copias de trabajo de Git existentes de ese repositorio. Elegir una copia ya abierta la enfoca; elegir una cerrada la abre en el mismo grupo.

Los worktrees agrupados siguen comportándose como espacios de trabajo normales de Herdr: se enfocan, se renombran, se cierran y tienen sus propias pestañas y paneles. La fila padre es el espacio de trabajo original. Cerrar la fila padre cierra todo el grupo en Herdr, pero no borra las carpetas de las copias ni las ramas.

Para borrar la copia de un worktree, usa Delete worktree checkout... en un espacio de trabajo hijo agrupado. Herdr ejecuta git worktree remove, primero pidiendo a Git que lo quite de forma segura. Si Git se niega porque la copia tiene ficheros modificados o sin seguimiento, Herdr vuelve a preguntar antes de forzar el borrado. Las ramas no se borran.

Conexión remota

La conexión remota gestiona su conexión SSH con keepalives temporales y, donde se admite, reutilización de la conexión por defecto.

[remote]
manage_ssh_config = true

Cuando está activo, herdr --remote escribe una configuración de SSH temporal y privada que incluye primero tus configuraciones de usuario y de sistema, y añade después valores de respaldo para ServerAliveInterval y ServerAliveCountMax. Tus propios ajustes de keepalive prevalecen. Los clientes Linux y macOS usan además un socket de control de OpenSSH privado por conexión para reutilizar la primera conexión autenticada; el OpenSSH de Windows no. Pon manage_ssh_config = false para que la conexión remota use ssh a secas, sin la configuración generada por Herdr ni el socket de control.

Atajos de teclado

Para una introducción guiada al prefijo y una configuración sin prefijo ya probada, mira Teclado.

Herdr tiene un modo prefijo parecido al de tmux. El prefijo por defecto es ctrl+b. Las cadenas de atajo son explícitas: prefix+n significa pulsar el prefijo configurado y después n; ctrl+alt+n es un atajo directo en modo terminal.

Una pequeña personalización de atajos tiene este aspecto:

[keys]
prefix = "ctrl+b"
goto = "prefix+g"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
focus_pane_left = "prefix+h"
navigate_workspace_down = "j"
navigate_pane_down = "ctrl+j"
split_horizontal = "prefix+minus"

El mapa de teclas por defecto es «prefijo primero», para que Herdr no robe entrada a shells, editores, tmux ni aplicaciones de terminal. Busca keys. en la referencia de configuración para ver todas las acciones y sus atajos por defecto. El panel de ayuda de la aplicación, en prefix+?, muestra los atajos activos.

Un atajo también puede ser una lista, cuando una acción necesita varios:

[keys]
next_tab = ["prefix+n", "ctrl+alt+]"]

Las acciones opcionales no tienen atajo por defecto. Asígnales uno con prefix+ para que funcionen en modo prefijo, o una combinación explícita con modificadores cuando quieras un atajo directo a propósito. Por ejemplo, para redimensionar paneles con una sola pulsación al estilo tmux, sin entrar en el modo de redimensionado:

[keys]
resize_pane_left = "ctrl+shift+alt+left"
resize_pane_down = "ctrl+shift+alt+down"
resize_pane_up = "ctrl+shift+alt+up"
resize_pane_right = "ctrl+shift+alt+right"

Las cadenas de tecla aceptan teclas sueltas, combinaciones con modificadores como ctrl+a, shift+n, alt+1 o cmd+k, y teclas especiales como enter, tab, esc, left, right, up y down. También se aceptan signos con nombre como minus, comma, ampersand, plus y backtick. Las teclas imprimibles directas y sin modificador, como n, son peligrosas porque interceptan lo que escribes; usa prefix+n salvo que quieras un atajo directo a propósito. Los campos navigate_workspace_* y navigate_pane_* son solo para el modo navegación y pueden usar teclas sueltas como j o k; no deben usar prefix+, esc, enter, tab, shift+tab, left, right ni 1 a 9 sin modificador. Las flechas izquierda y derecha son alias permanentes para navegar al panel izquierdo y derecho. Estos atajos del modo navegación son independientes de los atajos de acción generales como focus_pane_down = "prefix+j"; cuando ambos usan la misma tecla, gana el del modo navegación mientras ese modo está abierto. Alt, Cmd/Super y los signos con modificadores dependen de tu terminal y de tu configuración de tmux.

Si tienes atajos personalizados antiguos y quieres los nuevos valores por defecto, ejecuta herdr config reset-keys. Herdr hace una copia de config.toml, elimina [keys] y [[keys.command]], y usa los valores por defecto v2 integrados tras reiniciar o ejecutar herdr server reload-config.

Saltos por índice

Los atajos indexados usan 1..9 en los campos de atajo normales:

[keys]
switch_tab = "prefix+1..9"
switch_workspace = "prefix+shift+1..9"
focus_agent = "prefix+alt+1..9"

La tabla antigua [keys.indexed] se sigue leyendo por compatibilidad, pero las configuraciones nuevas deberían usar los campos de acción explícitos.

Atajos de comandos personalizados

Los comandos personalizados usan la misma sintaxis de atajos.

[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

type = "popup" abre una ventana emergente modal de sesión sin cambiar la disposición de la pestaña. La ventana recibe toda la entrada de la terminal, incluido Escape, hasta que su comando termina. width y height son opcionales; omítelos para el tamaño por defecto (la mitad), usa números para celdas de terminal, o cadenas como "80%" para un porcentaje del área de la terminal. Las dimensiones incluyen el borde de la ventana, y los valores menores que el mínimo se ajustan. Los comandos de ventana emergente no reciben HERDR_PANE_ID; usa HERDR_ACTIVE_PANE_ID para el panel en mosaico que hay debajo.

En Unix y macOS, un comando de ventana emergente también puede ofrecer una terminal improvisada sin añadir una división ni una pestaña:

[[keys.command]]
key = "prefix+t"
type = "popup"
command = "exec \"${SHELL:-sh}\""
description = "open scratch terminal"
width = "80%"
height = "80%"

En Windows, usa un comando de shell como command = "powershell.exe -NoLogo". Sal del shell para cerrar la ventana y volver a la vista de paneles en mosaico.

type = "pane" abre un panel temporal ampliado y lo cierra cuando el comando termina.

type = "shell" se ejecuta en segundo plano, sin panel.

type = "plugin_action" invoca el id de una acción de un plugin instalado. Usa el id cualificado cuando los ids de acción no sean únicos globalmente:

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

description es opcional. Si está, aparece en el panel de ayuda de atajos (prefix+?) en lugar de la etiqueta por defecto 'custom command'.

Los comandos personalizados reciben HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ACTIVE_WORKSPACE_ID, HERDR_ACTIVE_TAB_ID, HERDR_ACTIVE_PANE_ID y HERDR_ACTIVE_PANE_CWD cuando esos valores están disponibles. Los comandos de shell se ejecutan desde el directorio de trabajo del panel enfocado cuando Herdr puede detectarlo.

En Windows, las cadenas de comandos personalizados usan cmd.exe /d /c, así que las variables de entorno se escriben como %HERDR_BIN_PATH%. Para usar sintaxis de PowerShell, invócalo expresamente, por ejemplo powershell.exe -NoProfile -Command "...".

Tema

Elige un tema integrado:

[theme]
name = "catppuccin"

Busca theme.name en la referencia de configuración para ver todos los temas integrados. Usa terminal cuando quieras que los colores de la interfaz de Herdr sigan la paleta ANSI de tu terminal.

Para que Herdr cambie su propio tema cuando la terminal anuncie un cambio entre apariencia clara y oscura, activa el cambio automático:

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

auto_switch es false por defecto, así que las configuraciones existentes conservan el comportamiento manual. Si se omite light_name o dark_name, Herdr usa el hermano integrado del name configurado cuando existe, como tokyo-night/tokyo-night-day o gruvbox/gruvbox-light. Elegir un tema a mano en Ajustes desactiva auto_switch.

Puedes cambiar colores concretos:

[theme.custom]
sidebar_bg = "#181825"
active_row_bg = "#1e1e2e"
selection_bg = "#313244"
panel_bg = "reset"
accent = "#a6e3a1"
green = "#a6e3a1"
blue = "#89b4fa"
red = "#f38ba8"
yellow = "#f9e2af"

sidebar_bg da, opcionalmente, un fondo propio a la barra lateral de escritorio. Si se omite, la barra lateral conserva el fondo de la terminal. active_row_bg cambia el fondo del espacio activo y de la fila de agente enfocada, sin afectar a separadores ni barras de desplazamiento. selection_bg cambia el fondo de la fila del cursor del modo navegación en la barra lateral.

Los valores de color aceptan hexadecimal, colores con nombre, rgb(r,g,b) o alias de restablecimiento como reset, default, none y transparent.

Cuando auto_switch está activo, las subtablas opcionales para claro y oscuro se superponen a los colores personalizados compartidos:

[theme.custom]
accent = "#89b4fa"

[theme.custom.light]
panel_bg = "#eff1f5"
text = "#4c4f69"

[theme.custom.dark]
panel_bg = "#1e1e2e"
text = "#cdd6f4"

La paleta activa se aplica en este orden: tema integrado, [theme.custom], y después [theme.custom.light] o [theme.custom.dark]. Omitir las subtablas de modo conserva el comportamiento anterior de personalización compartida.

Interfaz y barra lateral

La barra lateral es el panel de control principal de Herdr. Busca ui. en la referencia de configuración para el tamaño, el modo plegado, el orden del panel de agentes, el comportamiento del ratón, los bordes de los paneles y otros ajustes de presentación.

ui.pane_borders acepta "auto" (por defecto: bordes solo en paneles divididos), "always" (enmarca también un panel único) u "off". Enmarcar un panel único requiere ui.pane_outer_borders = true, porque todos sus bordes son exteriores. Los valores booleanos existentes siguen valiendo: true equivale a "auto" y false a "off".

Pon tab_bar_position = "bottom" bajo [ui] para colocar la fila de pestañas de escritorio debajo de los paneles. Las barras de los modos prefijo, navegación, copia y redimensionado sustituyen temporalmente a la fila inferior mientras están activas. Por defecto es "top".

Configura un área de estado ordenada, al estilo tmux, en el borde derecho de la fila de pestañas:

[ui]
tab_bar_right = [
  { type = "zoom" },
  { type = "hostname" },
  { type = "datetime", format = "%H:%M" },
  { type = "text", text = "prod" },
  { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
]
tab_bar_right_separator = " · "

El área de estado está vacía por defecto. Añade zoom para mostrar una etiqueta fija ZOOM mientras la pestaña activa está ampliada; los marcadores Z de cada pestaña siguen siendo independientes. hostname, datetime y command se resuelven en el servidor de Herdr, así que herdr --remote muestra los valores de la máquina remota. Las entradas de fecha y hora usan el formato de strftime; las directivas que requieren un desplazamiento UTC o una marca de tiempo Unix, como %z y %s, se rechazan porque el valor es la hora local del servidor.

Las entradas de comando se ejecutan de inmediato y después cada interval_seconds, sin bloquear el pintado ni solaparse con una ejecución anterior. El intervalo puede ir de 1 a 31.536.000 segundos y el tiempo límite de 1 a 3.600. Herdr usa la última línea de la salida correcta, elimina las secuencias de control de terminal con prefijo ESC en vez de interpretar estilos, vacía la entrada tras un fallo, una salida vacía o superar timeout_seconds, y aporta el mismo contexto de espacio de trabajo, pestaña, panel, socket, binario y directorio de trabajo que los atajos de comandos personalizados. Los comandos funcionan en Linux, macOS y Windows, con /bin/sh -lc en Linux y macOS y cmd.exe /d /c en Windows.

Los separadores solo aparecen entre entradas visibles. Pon tab_bar_right_separator = "" para concatenarlas sin separador. En una fila de pestañas estrecha, el área de estado completa cede el sitio a las pestañas y sus controles.

Título de la ventana de la terminal exterior

Herdr emula las terminales de sus paneles, así que un título OSC 0/OSC 2 escrito dentro de un panel se queda en Herdr. Herdr escribe su propio título en la terminal donde corre, que es lo que leen los gestores de ventanas y las barras de pestañas de las terminales:

[ui]
window_title = "{hostname}: {workspace}"

Los tokens son {hostname}, {workspace}, {tab}, {pane} (el nombre manual del panel enfocado) y {terminal_title} (el título de terminal del panel enfocado, sin los fotogramas de spinner). Escribe {{ y }} para llaves literales. Un token sin valor se muestra vacío.

El título se genera en el servidor de Herdr, así que {hostname} es la máquina donde corren los paneles, también cuando te conectas con herdr --remote o ejecutas herdr por SSH. Pon window_title = "" para no tocar el título de la terminal exterior.

client.window_title.set sustituye el título configurado hasta que client.window_title.clear lo devuelve.

El estado de los agentes usa por defecto puntos de colores compactos. Para distinguir por forma, y no solo por color, los estados bloqueado, trabajando, hecho, en espera y desconocido, elige distinct symbols en Ajustes o configura:

[ui]
status_indicators = "symbols"

Los símbolos son estáticos, así que esta opción no activa animación de spinner.

Disposiciones de fila de la barra lateral

La barra lateral de escritorio desplegada pinta cada lista interior de rows como una línea. Estas son las disposiciones por defecto completas:

[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "machine", "workspace", "tab"],
  ["agent"],
]

[ui.sidebar.spaces]
row_gap = 0
rows = [
  ["state_icon", "workspace"],
  ["branch", "git_status"],
]

Las filas de agente aceptan estos tokens integrados:

• state_icon: icono de color del estado semántico del agente.
• state_text: idle, working, blocked, done o unknown, incluida la etiqueta informada cuando existe.
• machine: etiqueta de la máquina cuando el cliente tiene varias; se omite con una sola máquina local.
• workspace: nombre del espacio de trabajo.
• tab: nombre de la pestaña, si está disponible.
• pane: nombre del panel, si está disponible.
• agent: nombre del agente detectado o informado.
• terminal_title: último título OSC 0/2 de la terminal, normalizado por seguridad.
• terminal_title_stripped: el título de la terminal sin el primer glifo reconocido de actividad o spinner ni el espacio que le sigue.
• $name: metadato personalizado del panel llamado name.

Las filas de espacio aceptan estos tokens integrados:

• state_icon: icono de color del estado agregado de los agentes del espacio.
• state_text: texto del estado agregado.
• workspace: nombre del espacio de trabajo.
• branch: rama de Git, si está disponible.
• git_status: commits por delante y por detrás en Git, cuando no son cero.
• $name: metadato personalizado del espacio de trabajo llamado name.

Los tokens se pintan en el orden configurado. Herdr separa los valores adyacentes con · y usa un solo espacio después de state_icon. Los valores ausentes y sus separadores desaparecen; una fila desaparece cuando ninguno de sus tokens tiene valor. Las filas personalizadas existentes no cambian, así que añade machine expresamente si quieres la identidad de la máquina en una disposición multimáquina personalizada. Cada disposición admite como mucho 16 filas, con como mucho 16 tokens por fila.

Una entrada de token también puede ser una tabla de estilo en línea:

[ui.sidebar.agents]
rows = [
  ["state_icon", { token = "workspace", bold = false }, "tab"],
  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
]

fg acepta estrictamente #RGB o #RRGGBB. bold y dim aceptan booleanos. Los campos omitidos conservan el estilo contextual del token; un false explícito quita ese modificador. El estilo se aplica a una aparición, así que el mismo token puede verse distinto en otra fila o en otra personalización por agente. Un color de primer plano sustituye a todos los colores semánticos de esa aparición: por ejemplo, los contadores por delante y por detrás de un git_status con estilo usan un solo color en vez de su verde y rojo por defecto. Los estilos de token nunca cambian los separadores ni los fondos de fila.

Los tokens con valor de texto aceptan además hasta 16 rules ordenadas. Cada regla contiene exactamente una condición (equals, contains, starts_with, gt o lt) y personalizaciones opcionales de fg, bold y dim:

[ui.sidebar.agents]
rows = [
  ["state_icon", "workspace", "tab"],
  [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"],
  [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }],
]

Gana la primera regla que coincide. Sus campos de estilo indicados sustituyen a los valores por defecto de la aparición; los no indicados los heredan. Si ninguna regla coincide, se mantienen los valores por defecto. La comparación usa el valor completo del token, antes de recortarlo para mostrarlo. Pon hide = true en una regla para quitar el token que coincide y su separador; las filas que se quedan sin tokens también desaparecen. Por ejemplo, { token = "machine", fg = "#61afef", rules = [{ equals = "Local", hide = true }] } oculta el token de máquina cuando su etiqueta es exactamente Local. Compara la etiqueta, no el tipo de conexión. Con hide = false u omitido, el token sigue visible. Una regla sin personalizaciones también detiene la búsqueda y conserva los valores por defecto.

equals, contains y starts_with reciben cadenas y distinguen mayúsculas. Añade ignore_case = true para ignorarlas en ASCII; los caracteres no ASCII siguen distinguiéndolas. Las cadenas vacías siguen la comparación normal: un equals vacío solo coincide con un valor vacío, mientras que un contains o starts_with vacío coincide con cualquier valor presente.

gt y lt reciben umbrales numéricos finitos y comparan estrictamente mayor o menor, no igual. Los valores deben interpretarse por completo como números finitos; funcionan decimales y exponentes, pero no espacios, unidades, NaN ni infinito. ignore_case no se acepta en reglas numéricas. Las comparaciones usan coma flotante, no aritmética exacta de enteros grandes.

Las reglas funcionan con los tokens integrados de texto y con los $name personalizados en filas de agente, en las personalizaciones rows_by_agent y en filas de espacio. Los tokens personalizados comparan el valor informado: un $load que informa "90" selecciona rojo y negrita en el ejemplo, "60" selecciona amarillo y "90%" se queda en blanco. Los tokens no informados siguen desapareciendo. state_icon y el compuesto git_status aceptan solo estilos fijos, no reglas. Las condiciones desconocidas y las reglas mal formadas se rechazan al cargar la configuración; no se admiten expresiones regulares, búsqueda aproximada ni scripts.

row_gap controla las filas de terminal en blanco entre entradas, de forma independiente para los paneles de agentes y de espacios. Por defecto es 0, que las junta; ponlo a 1 para recuperar el espaciado anterior. No añade espacio entre las líneas de contenido declaradas en rows. Los hijos de worktree consecutivos e indentados siguen juntos como un grupo de espacio.

Sustituye la disposición completa de agente para un agente conocido bajo rows_by_agent:

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "state_text"],
  ["workspace", "tab"],
]

[ui.sidebar.agents.rows_by_agent]
claude = [
  ["state_icon", "agent", "state_text"],
  ["terminal_title_stripped"],
  ["workspace", "tab"],
]

Una personalización sustituye a rows; no la amplía. Las claves son IDs canónicos de agente, sensibles a mayúsculas, como claude, codex y pi. No se aceptan alias de detección como claude-code. Los agentes sin personalización, incluidos los informados a medida, usan rows.

Los tokens personalizados $name son valores dinámicos, no texto literal. Añade el token a una disposición e informa de su valor desde un script o un plugin:

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "$model"],
  ["$summary"],
  ["workspace", "tab"],
]

herdr pane report-metadata <pane_id> \
  --source my-agent-hook \
  --token model=opus \
  --token summary="reviewing authentication"

Usa herdr workspace report-metadata de la misma forma para los tokens personalizados de espacio. Los tokens personalizados no informados desaparecen.

Quien informa de los metadatos solo aporta valores; el estilo se queda en la configuración local de la barra lateral. Mira Referencia de la CLI: informar de metadatos para los límites, el borrado, la secuencia y la caducidad.

Los ajustes de filas de la barra lateral solo afectan a la barra lateral de escritorio desplegada. Las vistas plegada y móvil conservan sus disposiciones compactas.

Notificaciones

Herdr puede avisarte cuando un agente en segundo plano termina o necesita entrada:

[ui.toast]
delivery = "herdr"
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

Elige herdr para un aviso dentro de la aplicación, terminal para una notificación de la terminal exterior que también funciona por SSH, system para el servicio de notificaciones del sistema operativo local, u off para desactivar los avisos. Herdr no muestra avisos de la pestaña activa. Busca ui.toast en la referencia de configuración para las posiciones, el comportamiento del retardo y los ajustes de aviso al copiar.

En macOS, system prueba primero terminal-notifier y, si no está o falla, recurre a /usr/bin/osascript. Ese respaldo aparece como Editor de Scripts en el centro de notificaciones y no puede activar la terminal. Instala terminal-notifier con brew install terminal-notifier. En una terminal compatible y detectada, puede activar la aplicación de terminal al pulsar la notificación. Como alternativa, elige terminal para que una terminal exterior compatible gestione la notificación.

Sonido

Las notificaciones sonoras se reproducen en el cliente local de Herdr. Los sonidos personalizados deben ser ficheros mp3; Herdr resuelve las rutas relativas desde el directorio del fichero de configuración.

[ui.sound]
path = "sounds/notification.mp3"
done_path = "sounds/done.mp3"
request_path = "sounds/request.mp3"

path define un único sonido para todas las notificaciones sonoras. done_path y request_path sustituyen solo los sonidos de terminado y de necesita entrada.

Las personalizaciones de sonido por agente aceptan default, on u off. Usa como claves las etiquetas de agente detectadas, como claude, codex, devin o droid. Droid está silenciado por defecto.

[ui.sound.agents]
droid = "off"
claude = "on"

Configuración avanzada

Busca en la referencia de configuración los límites del historial, los lanzamientos anidados y demás ajustes avanzados o experimentales. Lee Estado de la sesión y restauración antes de activar el historial de pantalla de los paneles; esa guía explica el compromiso de seguridad de guardar el contenido de los paneles.

Gráficos Kitty

Herdr pinta por defecto las imágenes de los paneles en las terminales exteriores compatibles. Las ventanas emergentes, los menús y las notificaciones ocultan temporalmente solo las imágenes que tapan. Las imágenes no tapadas siguen visibles, y las ocultas vuelven cuando se destapan. Las imágenes no se atenúan con los fondos de los diálogos.

Para desactivar el pintado de gráficos y la API de gráficos de los paneles:

[terminal]
kitty_graphics = false

El ajuste antiguo experimental.kitty_graphics se sigue aceptando en las configuraciones existentes. terminal.kitty_graphics tiene prioridad cuando están los dos.

Cambiar este ajuste requiere reiniciar el servidor de Herdr afectado o volver a conectar el cliente. En sesiones remotas, el ajuste del servidor controla el análisis de gráficos de los paneles y la disponibilidad de la API, mientras que el del cliente local controla la salida a la terminal exterior.

Restauración de la sesión del agente

Herdr reanuda por defecto las conversaciones de los agentes compatibles después de reiniciar el servidor:

[session]
resume_agents_on_restore = true

Solo pueden reanudarse los paneles con una referencia de sesión nativa válida de una integración oficial; los demás se restauran como shells normales. Mira Estado de la sesión y restauración para los agentes compatibles y el comportamiento de la persistencia.

Seguimiento del cursor para IME

En macOS, las interfaces de agentes que ocultan el cursor de hardware pueden impedir que las ventanas de candidatos de los métodos de entrada nativos sigan al panel enfocado. Muestra un cursor de anclaje en esos paneles con:

[experimental]
reveal_hidden_cursor_for_cjk_ime = true
cjk_ime_agents = ["claude", "pi", "codex"]

Limitar cjk_ime_agents evita mostrar un cursor de hardware extra en aplicaciones que no lo necesitan. Busca estas claves en la referencia de configuración para los nombres de agente aceptados y las formas del cursor.

Cambio de fuente de entrada en el prefijo

En macOS y Windows, Herdr puede cambiar temporalmente a una fuente de entrada ASCII mientras están activos los comandos de prefijo y los modos lanzados desde el prefijo:

[experimental]
switch_ascii_input_source_in_prefix = true

En macOS cambia a la disposición de teclado ASCII actual; en Windows cambia el IME a entrada en inglés (ASCII). Herdr restaura la fuente de entrada anterior al volver a la entrada de terminal o al entrar en un campo de texto. Este ajuste no tiene efecto en otras plataformas.

En Windows, solo el IME coreano

En Windows, el soporte se limita por ahora al IME coreano. Con un IME de cualquier otro idioma, este ajuste deja la fuente de entrada como está.

Variables de entorno

Variable	Para qué sirve
HERDR_CONFIG_PATH	Cambia la ruta del fichero de configuración.
HERDR_SESSION	Selecciona una sesión con nombre para los comandos de la CLI.
HERDR_SOCKET_PATH	Cambia la ruta del socket, a bajo nivel.
HERDR_PROCESS_DETECTION	Estrategia de detección de procesos en Linux: native (por defecto) o child-groups (opcional).
HERDR_LOG	Filtro de registro, por ejemplo HERDR_LOG=herdr=debug.
HERDR_DISABLE_SOUND	Desactiva la reproducción de sonido aunque [ui.sound] enabled = true.

Registros

Los registros ayudan a diagnosticar avisos de arranque, el estado de las integraciones o el comportamiento de la API de socket.

Ficheros de registro habituales:

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

Los registros rotan automáticamente. Cuando informes de un problema, incluye el registro actual y los rotados.