Instalar herdr: guía básica

Objetivo

Al terminar vas a tener herdr instalado y corriendo en tu máquina, con un workspace activo sobre un proyecto real y un agente de código detectado en la barra lateral.

herdr es un multiplexor de terminales pensado para trabajar con agentes de código (Claude Code, Codex, Cursor, opencode y otros). Mantiene las sesiones vivas en segundo plano y muestra el estado de cada agente —trabajando, bloqueado, terminado— sin que tengas que revisar panel por panel.

Prerrequisitos

macOS, Linux o Windows x86_64 (en Windows ARM64 corre por emulación).
Acceso a una terminal con permisos para instalar binarios en tu PATH.
Un proyecto local sobre el que quieras trabajar.
Opcional: un agente de código ya instalado (por ejemplo Claude Code) para verlo detectado al final.

Esta guía cubre la versión v0.8.2 de herdr.

Pasos

1. Instalar el binario

Elige el método según tu sistema.

macOS / Linux (script):

curl -fsSL https://herdr.dev/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

Windows (CMD, si PowerShell está bloqueado):

curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

Homebrew:

brew install herdr

mise:

mise use -g herdr

Nix (flake): reemplaza v0.x.y por el último tag de release.

nix profile install github:herdrdev/herdr/v0.x.y

Manual: descarga el binario para tu sistema desde las releases de GitHub, hazlo ejecutable y agrégalo al PATH.

2. Verificar la instalación

herdr --version

Verificación esperada: imprime la versión instalada (por ejemplo herdr 0.8.2). Si la terminal responde "command not found", abre una sesión nueva para que tome el PATH actualizado.

3. Arrancar herdr sobre un proyecto

cd ruta/a/tu/proyecto
herdr

Esto levanta el servidor en segundo plano y crea un workspace para ese directorio. Vas a entrar a la interfaz de herdr con un pane de terminal activo.

Verificación esperada: ves la barra lateral de herdr y el prompt de tu shell dentro del pane.

4. Lanzar un agente y verlo detectado

Dentro del pane, arranca tu agente como siempre:

claude

herdr lo detecta solo y muestra su estado en la barra lateral. Puedes dividir el pane con prefix+v (split a la derecha) o prefix+- (split abajo); el prefijo por defecto es ctrl+b.

5. Detach y reattach

Presiona prefix+q o cierra la terminal. Todo sigue corriendo en segundo plano. Para volver:

herdr

6. Detener el servidor

Cuando termines:

herdr server stop

Resultado esperado

herdr --version imprime la versión.
herdr abre un workspace sobre tu proyecto y sobrevive a cerrar la terminal.
Un agente lanzado dentro de un pane aparece con su estado en la barra lateral.

Troubleshooting

Problemas comunes

herdr: command not found después de instalar: el instalador agregó el binario al PATH pero tu shell actual no lo tomó. Abre una terminal nueva o recarga tu perfil (source ~/.bashrc, source ~/.zshrc).
El agente no se detecta: ejecuta herdr agent list para ver qué reconoce, y herdr agent explain <target> --json para entender por qué un comando no coincide.
Los keybindings no responden: probablemente tu terminal o el sistema operativo están capturando ctrl+b antes que herdr. Revisa la guía de teclado.
Logs del servidor: ~/.config/herdr/ en Linux/macOS, %APPDATA%\herdr\ en Windows.

Siguiente paso

Configura herdr a tu gusto editando ~/.config/herdr/config.toml (o %APPDATA%\herdr\config.toml en Windows). Puedes ver los valores por defecto con herdr --default-config y recargar sin reiniciar con herdr server reload-config.