En esta guía vamos a instalar y configurar Herdr para desarrollo agéntico, paso a paso.

Instalación asistida por IA

Si prefieres que un agente haga el trabajo por ti, copia este prompt y pégalo en Claude Code (o en el agente que uses). Sigue esta misma guía: comprueba cada paso antes de ejecutarlo y pregunta antes de tocar nada opinable.

Ver el prompt completo 
Quiero instalar y configurar Herdr (https://herdr.dev) en esta máquina para desarrollo agéntico. Trabaja paso a paso, comprueba antes de cada paso si ya está hecho (todo debe ser seguro de re-ejecutar) y pídeme confirmación antes de los pasos opcionales.

1. Instala Herdr. En macOS usa Homebrew: brew install herdr. Si no hay Homebrew, propón el script de instalación oficial de https://herdr.dev y espera mi confirmación.
2. Verifica la instalación: herdr server status y herdr session list deben responder sin errores.
3. Instala la integración con mi agente. Para Claude Code: herdr integration install claude. Si uso otro, consulta https://herdr.dev/docs/integrations/ y pregúntame cuál.
4. Crea una sesión con el nombre de mi proyecto principal (pregúntame el nombre) y comprueba que sobrevive al cierre del terminal reconectando con herdr session attach <nombre>.
5. Opcional: configura Ghostty como terminal dedicado a Herdr aplicando mi configuración de https://github.com/SergioDiez/SergioDiez/blob/master/configs/ghostty/config y la de Herdr de https://github.com/SergioDiez/SergioDiez/blob/master/configs/herdr/config.toml. Haz copia de seguridad de las configuraciones existentes antes.
6. Opcional: si mi shell es zsh y EDITOR es nvim o vim, comprueba si opt+flecha descoloca el cursor en el terminal; si es así, aplica en mi .zshrc el arreglo de forzar el modo emacs (bindkey -e) con la navegación por palabras explícita.

Al terminar, enséñame un resumen de lo que has hecho, lo que has omitido y cómo verificarlo. La guía completa está en https://sergiodiez.es/blog/instalar-configurar-herdr

Instalación

Para descargar Herdr podemos navegar a su página web oficial; la forma más sencilla es utilizar el script de instalación o Homebrew.

En mi caso utilizaré Homebrew:

brew install herdr

Una vez instalado, ejecuta el comando herdr en el terminal. Esto abrirá una nueva sesión de Herdr. Lo primero que haré será renombrarla a dev, ya que será la que use para el desarrollo general; aquí puedes utilizar el nombre de un proyecto, por ejemplo.

Menú contextual de una sesión de Herdr con las opciones Rename y Close

Ahora, prueba a cerrar el terminal por completo y vuelve a abrirlo. Una vez abierto, escribe herdr y verás que la sesión anterior se sigue ejecutando. Esto es porque Herdr se ejecuta en un servidor propio, el Herdr server. Si quisieras detener la ejecución de este servidor, ejecuta el comando:

herdr server stop

Para visualizar las sesiones activas, usa herdr session list. Con herdr session attach <nombre> puedes conectarte a la sesión.

Uso

Prefix

Con la combinación ctrl+b se entra en el modo prefix. Esto permite ejecutar acciones con el teclado.

Abrir un nuevo tab

Pulsa ctrl+b y a continuación c. Esto creará una nueva pestaña en la parte superior. Para navegar rápido entre pestañas puedes pulsar ctrl+b y luego el número de la pestaña (su orden); por ejemplo, 1 para volver a la anterior.

Abrir un nuevo panel

Pulsa ctrl+b y luego v para crearlo a la derecha, o - para crearlo en la parte inferior.

Cerrar un panel

Pulsa ctrl+b y luego x para cerrar el panel.

De momento dejaremos los atajos aquí, como los más simples; habrá una guía avanzada para utilizar más atajos y combinaciones con el teclado.

Usar Claude Code

Aquí explicaremos cómo utilizar Claude Code con Herdr, aunque se puede configurar cualquier otro agente, como Codex, OpenCode… Consulta la lista de integraciones.

Instalación

Para usar claude, instala la integración ejecutando el siguiente comando:

herdr integration install claude

Espacios

En la parte superior izquierda se muestra la sección spaces. Aquí podemos configurar tantos espacios como queramos; piensa en ellos como proyectos distintos. También puedes hacer clic derecho sobre un espacio para crear un nuevo worktree, lo que nos permite trabajar en tareas simultáneas sobre el mismo código.

Cada espacio puede tener varias pestañas, que se crean en la parte superior de la pantalla.

Agentes

En la sección izquierda, en el bloque agents, se muestran todos los agentes en ejecución, independientemente del espacio o la pestaña donde estén corriendo.

Bloque de agentes de Herdr con un agente en ejecución y otro listo

Junto al nombre se muestra su estado, así puedes comprobar de un vistazo si el agente está trabajando, listo o bloqueado esperando una respuesta del usuario. Cuando un agente se bloquea o termina, Herdr reproduce un sonido para avisarte.

En este ejemplo, una instancia está esperando una respuesta del usuario:

Bloque de agentes de Herdr con la instancia test emails bloqueada esperando al usuario

Al hacer clic en cualquier agente, Herdr te lleva al espacio y la pestaña donde se está ejecutando, por lo que es muy fácil seguirles la pista.

Herdr desde el móvil

Una de las cosas que más me gustan de Herdr es que no necesita app móvil: como todo vive en el Herdr server, basta con conectarse por SSH desde el teléfono y abrir la misma sesión persistente, tal y como explica su documentación. La interfaz se adapta a pantallas estrechas, así que puedes revisar el estado de los agentes, cambiar de espacio o mirar un panel desde cualquier parte.

En mi caso hago la conexión con Tailscale, que crea una red privada basada en WireGuard entre mis dispositivos. Así no expongo el puerto SSH a internet, y funciona igual con WiFi que con datos móviles.

Los pasos:

  1. Instala Tailscale en el ordenador y en el móvil, e inicia sesión con la misma cuenta en ambos; eso los mete en la misma tailnet.
  2. Activa el acceso por SSH en el ordenador. En macOS: Ajustes del Sistema → General → Compartir → Sesión remota.
  3. Desde el móvil, con un cliente SSH, conéctate usando el nombre del equipo en la tailnet. En mi caso uso Termius en Android; si tienes iPhone, la documentación recomienda moshi:
ssh usuario@mi-mac
herdr

Y ya está: la misma sesión de Herdr que dejaste en el escritorio, en el bolsillo.

Sesión de Herdr abierta desde el iPhone por SSH, con la interfaz adaptada a la pantalla estrecha

Gracias a MagicDNS, el nombre del equipo funciona desde cualquier red sin importar qué IP tenga en cada momento; no hace falta configurar nada más.

Si te conectas a un portátil, evita que se suspenda o la sesión SSH se cortará. En macOS basta con dejar caffeinate -s ejecutándose en un terminal: el Mac se mantendrá despierto mientras esté conectado a la corriente, sin tocar los ajustes de energía.

Mi configuración

Esta sección es totalmente subjetiva: recoge cómo he configurado el terminal y Herdr a mi gusto. Tómala como inspiración, no como la forma «correcta» de hacerlo.

El terminal

He configurado Ghostty para que sea, simplemente, mi terminal de Herdr. Para el resto de tareas utilizo Kitty. Esto significa que mi Ghostty arranca directamente con Herdr y tiene desactivadas las pestañas y demás funcionalidades propias: es una única superficie a pantalla completa donde vive Herdr, que ya dibuja su propia interfaz.

Configuración de Ghostty

Puedes ver mi configuración actual de Ghostty en mi repositorio de GitHub.

Lo más relevante: command apunta al binario de herdr para que se lance al abrir la app, la barra de título está oculta y la ventana se abre maximizada y sin padding, y el tema está fijado en oscuro (TokyoNight). Antes cambiaba automáticamente con la apariencia de macOS, pero al conectarme desde el móvil el cliente SSH va siempre en oscuro, y el cambio de tema a mitad de sesión reestilizaba las instancias de Claude en marcha; con el tema fijo no hay sorpresas.

Sobre la fuente: uso JetBrains Mono, que es gratuita y de código abierto. Si no la tienes instalada, en macOS puedes hacerlo con brew install --cask font-jetbrains-mono; y si prefieres otra, basta con cambiar las líneas font-family de la configuración por tu fuente monoespaciada favorita (o eliminarlas para usar la fuente por defecto de Ghostty).

Configuración de Herdr

Mi configuración de Herdr también está en el repositorio. Fija el mismo tema oscuro (tokyo-night), ordena el panel de agentes por espacios y define un par de atajos para plugins.

Lo más útil que he añadido últimamente es una protección para cmd+w: un pequeño script (close-pane-safe.sh, también en el repositorio) comprueba si el panel tiene un agente en marcha antes de cerrarlo. Si hay una instancia de Claude trabajando o bloqueada, la primera pulsación solo muestra un aviso, y hay que pulsar cmd+w otra vez en menos de 10 segundos para cerrarlo de verdad. Así es imposible cargarse una sesión por error.

Configuración de ZSH

Solo hizo falta un ajuste en mi .zshrc para que todo funcionara bien: al tener EDITOR=nvim, zsh activa por defecto el keymap de vi, y como las secuencias de opt+tecla empiezan por ESC, cada opt+flecha u opt+borrar cambiaba a modo comando de vi y descolocaba el cursor. La solución es forzar el modo emacs y declarar la navegación por palabras explícitamente:

bindkey -e
bindkey '^[^?' backward-kill-word   # opt+borrar
bindkey '^[[1;3D' backward-word     # opt+izquierda
bindkey '^[[1;3C' forward-word      # opt+derecha

Atajos de teclado

Los atajos de Herdr funcionan con el prefix ctrl+b, pero yo quería usar los atajos nativos de macOS. El truco está en Ghostty: cada keybind envía la secuencia del prefix correspondiente, así que para Herdr es como si hubiera pulsado ctrl+b y la tecla de la acción.

Los más importantes:

  • cmd+d: nuevo panel a la derecha.
  • cmd+shift+d: nuevo panel en la parte inferior.
  • cmd+t: nueva pestaña.
  • cmd+w: cerrar el panel actual (con la protección de doble pulsación si hay un agente en marcha, como vimos arriba).
  • cmd+1..9: cambiar de pestaña por su orden.

Y algunos extra que también uso a diario:

  • cmd+shift+w: cerrar la pestaña actual.
  • cmd+f: abre el scrollback del panel en $EDITOR, donde puedo buscar con /.
  • shift+enter: inserta un salto de línea sin enviar el comando, útil escribiendo prompts largos.