Integraciones

Herdr detecta automáticamente los agentes compatibles. Instala las integraciones oficiales cuando quieras restauración nativa de la sesión del agente, informes directos de ciclo de vida, o ambas cosas. Mira Agentes para el modelo completo de autoridad del estado.

Instalar integraciones

Abre los ajustes dentro de Herdr y usa la pestaña de integraciones para instalar las recomendadas para los agentes que estén en tu PATH, o ejecuta los comandos a mano:

herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install mastracode
herdr integration install antigravity-cli
herdr integration install grok

Desinstalar integraciones

herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall devin
herdr integration uninstall droid
herdr integration uninstall kimi
herdr integration uninstall opencode
herdr integration uninstall kilo
herdr integration uninstall hermes
herdr integration uninstall qodercli
herdr integration uninstall qwen
herdr integration uninstall letta
herdr integration uninstall cursor
herdr integration uninstall mastracode
herdr integration uninstall antigravity-cli
herdr integration uninstall grok

Herdr guarda las configuraciones de las integraciones de forma atómica en Linux y macOS y en los ficheros nuevos; los ficheros de Windows existentes conservan sus permisos mediante una actualización en el sitio con copia previa. Si Windows informa de una copia de seguridad, cierra el agente e inspecciona la configuración antes de reintentar: descarta (no restaures) un .herdr-backup.pending incompleto solo después de verificar la configuración, o restaura el contenido de un .herdr-backup completo en el fichero existente si hace falta (si no existe, establece antes los permisos previstos); después verifica la configuración y elimina la copia.

Cómo usa Herdr las integraciones

Herdr usa las integraciones de dos maneras:

Tipo de integración	Agentes	Efecto
Autoridad de ciclo de vida	Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, MastraCode	Cuando está instalada e informando activamente para el panel, los eventos del gancho o plugin dictan `idle`, `working` y `blocked`. Herdr no usa además el manifiesto de pantalla como respaldo para esa misma autoridad.
Identidad de sesión	Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, Hermes Agent, Antigravity CLI, Grok CLI	La integración informa de las referencias de sesión nativas para la restauración. El estado sigue viniendo de la detección por manifiesto de pantalla de Herdr.

Las integraciones a medida también pueden informar de un estado que no se ve en la interfaz nativa de la terminal. No necesitan estar integradas en Herdr ni usar un ejecutable de agente reconocido.

Integra tu propio agente

Un agente que corre en un panel de Herdr hereda HERDR_ENV, HERDR_PANE_ID, HERDR_BIN_PATH y HERDR_SOCKET_PATH. Si el agente expone ganchos de ciclo de vida, úsalos para informar del estado semántico a través de la CLI de Herdr:

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source custom:my-agent \
  --agent my-agent \
  --state working

Informa de idle cuando el agente esté listo para recibir entrada y de blocked cuando necesite una decisión del usuario. Usa --message para describir un bloqueo. Cuando el agente termine, libera la autoridad de ciclo de vida de esa misma fuente:

"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
  --source custom:my-agent \
  --agent my-agent

Informa solo cuando HERDR_ENV=1 y las variables necesarias estén presentes. Así la integración no hace nada fuera de Herdr. Mantén --source estable y único para la integración. Si los informes pueden llegar desordenados, incluye un --seq estrictamente creciente; Herdr ignora los números de secuencia atrasados de la misma fuente.

Puedes incluir --agent-session-id o --agent-session-path con report-agent, o usar pane report-agent-session cuando la identidad de la sesión cambie con independencia del estado. Herdr expone esa referencia a través de sus API de panel y de agente. La restauración automática de la sesión requiere además que Herdr sepa cómo lanzar ese agente y reanudar la sesión referenciada.

Usa HERDR_BIN_PATH y los comandos de la CLI para integraciones portables. El código que necesite IPC directo puede enviar las peticiones equivalentes pane.report_agent, pane.report_agent_session y pane.release_agent descritas en la API de socket.

El informador de Herdr integrado en Prime Agent es un ejemplo real. Solo se activa dentro de Herdr, traduce los eventos del agente a working, idle y blocked, conserva el orden de los informes entre sesiones y libera la autoridad al salir.

Algunas integraciones informan de referencias de sesión nativas. Herdr usa las referencias oficiales para reanudar los paneles de Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode y Antigravity CLI después de reiniciar el servidor, a menos que [session] resume_agents_on_restore = false lo desactive.

La restauración nativa requiere integraciones actuales: Pi versión 2, OMP versión 3, Claude Code versión 6, Codex versión 5, GitHub Copilot CLI versión 2, Devin CLI versión 2, Droid versión 2, Kimi Code CLI versión 3, Qoder CLI versión 2, Qwen Code versión 1, Letta Code versión 1, Cursor Agent CLI versión 1, Grok CLI versión 2, OpenCode versión 5, Kilo Code CLI versión 1, Hermes Agent versión 5, MastraCode versión 1 o Antigravity CLI versión 1. Comprueba las versiones instaladas con herdr integration status.

Pi

Instala la integración de Pi:

herdr integration install pi

Herdr escribe la extensión incluida en:

~/.pi/agent/extensions/herdr-agent-state.ts

Si PI_CODING_AGENT_DIR está definida, Herdr escribe en $PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts. Herdr crea el directorio de extensiones cuando el directorio del agente Pi ya existe. Desinstalar elimina solo ese fichero de extensión.

OMP

Instala la integración de OMP:

herdr integration install omp

Herdr escribe la extensión incluida en:

~/.omp/agent/extensions/herdr-omp-agent-state.ts

Herdr usa PI_CODING_AGENT_DIR como directorio completo del agente cuando está definida. Si no, usa $HOME/$PI_CONFIG_DIR/agent cuando PI_CONFIG_DIR está definida, y en último caso ~/.omp/agent. Si Pi y OMP resuelven al mismo directorio de extensiones, Herdr rechaza la instalación de OMP para que Pi no pueda cargar la extensión de OMP. Configura directorios de agente separados antes de instalar ambas integraciones. Herdr crea el directorio de extensiones cuando el directorio del agente OMP ya existe. Desinstalar elimina solo ese fichero de extensión.

La integración de OMP informa de omp como etiqueta de agente, del estado de ciclo de vida y de la identidad de sesión nativa a través de la API de socket de Herdr. No requiere detección nativa del proceso para el ejecutable omp, y Herdr puede reanudar un panel de OMP con omp --resume=<sesión> tras reiniciar el servidor.

Claude Code

Instala el gancho de Claude Code:

herdr integration install claude

El gancho informa de la identidad de sesión de Claude Code al socket local de Herdr al iniciar la sesión. El estado de Claude Code viene de la detección por manifiesto de pantalla de Herdr.

La integración de Claude v10 solo reconoce las fuentes documentadas de SessionStart: startup, resume, clear, compact y fork. Así evita que los eventos new y load de Grok lancen el gancho de Herdr para Claude importado, sin desactivar otros ganchos compatibles con Claude. Reinstala la integración de Claude después de actualizar para migrar el comodín anterior. Los valores de fuente nuevos de Claude requieren una actualización de la integración.

Herdr usa ~/.claude por defecto, o CLAUDE_CONFIG_DIR cuando está definida. El directorio de configuración de Claude debe existir ya. La instalación escribe hooks/herdr-agent-state.sh y añade las entradas de gancho de Herdr a settings.json. Desinstalar elimina las entradas de gancho correspondientes y borra el script.

Codex

Instala el gancho de Codex:

herdr integration install codex

El gancho de Codex informa de la identidad de sesión a través de la misma API de socket local que usan las demás integraciones. El estado de Codex viene de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.codex por defecto, o CODEX_HOME cuando está definida. El directorio de configuración de Codex debe existir ya. La instalación escribe herdr-agent-state.sh, actualiza hooks.json y garantiza [features] hooks = true en config.toml. También elimina la marca obsoleta de nivel superior codex_hooks si existe. Desinstalar elimina las entradas de Herdr de hooks.json y borra el script, pero deja config.toml como está.

GitHub Copilot CLI

Instala el gancho de GitHub Copilot CLI:

herdr integration install copilot

El gancho de Copilot informa de la identidad de sesión a través de la misma API de socket local que usan las demás integraciones. El estado de Copilot viene de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.copilot por defecto, o COPILOT_HOME cuando está definida. El directorio de configuración de Copilot debe existir ya. La instalación escribe hooks/herdr-agent-state.sh y añade una entrada de gancho SessionStart a settings.json. Desinstalar elimina las entradas de Herdr de settings.json y borra el script.

Cuando Copilot emite un evento con sesión, Herdr puede usar el id informado para reanudar el panel con copilot --resume=<id>.

Devin CLI

Instala el gancho de Devin CLI:

herdr integration install devin

El gancho informa de la identidad de sesión nativa a partir de los eventos de sesión, prompt, uso de herramientas, permisos y parada de Devin. El estado de Devin sigue viniendo de la detección por manifiesto de pantalla y OSC de Herdr, porque los ganchos de Devin no emiten una transición de estado fiable después de cada cancelación de permiso o interrupción del usuario.

Herdr usa $XDG_CONFIG_HOME/devin cuando XDG_CONFIG_HOME está definida. Si no, usa ~/.config/devin en Linux y macOS o %APPDATA%\devin en Windows. El directorio de configuración de Devin debe existir ya. La instalación escribe herdr-agent-state.sh en Unix o herdr-agent-state.ps1 en Windows y añade las entradas de gancho de Herdr a config.json. El gancho refresca la referencia de sesión mientras Devin corre. Desinstalar elimina las entradas de Herdr de config.json y borra el script.

Herdr reanuda las sesiones de Devin guardadas con devin --resume <id>. La detección nativa por manifiesto de pantalla sigue siendo la autoridad del estado, esté o no instalado el gancho.

Kimi Code CLI

Instala el gancho de Kimi Code CLI:

herdr integration install kimi

El gancho informa a Herdr de la identidad de sesión y del estado de ciclo de vida de Kimi, para la restauración nativa y para un estado idle, working y blocked autoritativo. Requiere Kimi Code CLI 0.14.0 o posterior.

Herdr usa ~/.kimi-code por defecto, o KIMI_CODE_HOME cuando está definida. El directorio de configuración de Kimi Code debe existir ya. La instalación escribe hooks/herdr-agent-state.sh y añade a config.toml entradas [[hooks]] gestionadas por Herdr. Desinstalar elimina el bloque de configuración gestionado por Herdr y borra el script.

Herdr reanuda las sesiones de Kimi guardadas con kimi --session <id>.

Droid

Instala el gancho de Droid:

herdr integration install droid

El gancho de Droid informa de la identidad de sesión a través de la misma API de socket local que usan las demás integraciones. El estado de ciclo de vida sigue viniendo de la detección por manifiesto de pantalla de Herdr, porque los ganchos de Droid no cubren todas las transiciones.

Herdr usa ~/.factory para los ganchos de Droid. El directorio de configuración de Factory debe existir ya. La instalación escribe hooks/herdr-agent-state.sh, añade una entrada de gancho SessionStart de Herdr a settings.json y elimina las entradas antiguas de Herdr para Droid de hooks.json si existen. Desinstalar elimina las entradas de Herdr de ambos ficheros y borra el script.

Cuando Droid emite un evento de inicio de sesión, Herdr puede usar el id informado para reanudar el panel con droid --resume <id>.

OpenCode

Instala el plugin de OpenCode:

herdr integration install opencode

La integración admite OpenCode V1 1.18.29 o posterior y OpenCode V2 (probado con la beta 19242). El directorio de configuración de OpenCode debe existir ya. Herdr instala el punto de entrada del servidor en ~/.config/opencode/plugins/herdr-agent-state.js, el plugin compartido de la interfaz en herdr-tui-session.js y un punto de entrada de interfaz para V2 en herdr-opencode/tui.js, todo en ese directorio de configuración.

La instalación registra el plugin de interfaz V1 en tui.jsonc y el de V2 en cli.json, conservando las demás preferencias y plugins. Un registro V1 existente en tui.json también cuenta como instalado y se reutiliza sin crear tui.jsonc. Desinstalar elimina el registro de Herdr de ambos ficheros de configuración de la interfaz, conservando los ficheros y las demás preferencias. Si OpenCode todavía tiene preferencias de interfaz V1 pendientes de importar (tui.json o kv.json), Herdr pospone el registro para que se ejecute la migración del primer arranque; arranca opencode2 una vez y reinstala después la integración. En caso contrario, Herdr crea cli.json con el registro del plugin. Reinicia la interfaz de OpenCode después de instalar. Desinstalar elimina los ficheros del plugin gestionados y sus entradas de configuración.

En V2, los informes de ciclo de vida corren en la interfaz local del panel, que asocia los eventos con su sesión raíz seleccionada incluso cuando varios paneles comparten un mismo servidor de OpenCode. La finalización y la interrupción limpian el estado de trabajo; las peticiones de permiso pendientes, los formularios pendientes y las ejecuciones fallidas mantienen el panel bloqueado. Los clientes V2 Mini y sin interfaz no ejecutan el plugin de interfaz y, por tanto, no aportan estos informes.

El plugin informa del estado de ciclo de vida y de la identidad de sesión mientras OpenCode corre en un panel de Herdr. Cuando OpenCode emite un evento con sesión, Herdr puede usar el id informado para reanudar el panel con opencode --session <id>. La detección nativa por manifiesto de pantalla sigue disponible cuando el plugin no está instalado.

Kilo Code CLI

Instala el plugin de Kilo Code CLI:

herdr integration install kilo

Herdr escribe el plugin en ~/.config/kilo/plugin/herdr-agent-state.js. El directorio de configuración de Kilo debe existir ya. Desinstalar elimina solo ese fichero.

El plugin informa del estado de ciclo de vida y de la identidad de sesión mientras Kilo corre en un panel de Herdr. Cuando Kilo emite un evento con sesión, Herdr puede usar el id informado para reanudar el panel con kilo --session <id>. La detección nativa por manifiesto de pantalla sigue disponible cuando el plugin no está instalado.

Hermes Agent

Instala el plugin de Hermes Agent:

herdr integration install hermes

Herdr escribe plugins/herdr-agent-state/ bajo el directorio de Hermes y activa herdr-agent-state en su config.yaml. HERMES_HOME es ~/.hermes por defecto en Unix y %LOCALAPPDATA%\hermes en Windows. El directorio de configuración de Hermes debe existir ya. Reinicia Hermes después de instalar para que cargue el plugin. Desinstalar elimina el directorio del plugin y quita herdr-agent-state de plugins.enabled.

El plugin informa del id de sesión reanudable mientras Hermes corre en un panel de Herdr. Herdr usa la detección por manifiesto de pantalla para working, idle y blocked, y puede usar el id informado para reanudar el panel con hermes --resume <id>.

Qoder CLI

Instala el gancho de Qoder CLI:

herdr integration install qodercli

El gancho informa a Herdr de la identidad de sesión de Qoder CLI para la restauración nativa. El estado de ciclo de vida sigue viniendo de la detección por manifiesto de pantalla de Herdr, porque los ganchos de Qoder no cubren todas las transiciones.

Herdr usa ~/.qoder por defecto, o QODER_CONFIG_DIR cuando está definida. El directorio de configuración de Qoder debe existir ya. La instalación escribe hooks/herdr-agent-state.sh y añade las entradas de gancho de Herdr a settings.json. Desinstalar elimina las entradas correspondientes y borra el script.

Herdr reanuda las sesiones de Qoder CLI guardadas con qodercli --resume <id>.

La detección nativa por manifiesto de pantalla sigue disponible cuando el gancho no está instalado.

Qwen Code

Instala el gancho de Qwen Code:

herdr integration install qwen

El gancho SessionStart informa solo de la identidad de sesión de Qwen Code para la restauración nativa. El estado de ciclo de vida sigue a cargo de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.qwen por defecto, o QWEN_HOME cuando está definida. El directorio de configuración de Qwen debe existir ya. La instalación escribe hooks/herdr-agent-session.sh (hooks/herdr-agent-session.ps1 en Windows) y añade una entrada de Herdr a settings.json. Desinstalar elimina solo la entrada correspondiente y el script gestionado.

Herdr reanuda las sesiones de Qwen Code guardadas con qwen --resume <id>.

Letta Code

La instalación de la integración de Letta Code es experimental y solo por CLI. No aparece en la pantalla de integraciones de Ajustes ni en la API JSON de integraciones. herdr integration status la muestra como letta (experimental). La detección del agente y herdr agent start --kind letta funcionan con independencia de esta restricción.

Instala el gancho de Letta Code:

herdr integration install letta

El gancho silencioso SessionStart informa del ID de conversación para la restauración nativa. El estado de Letta Code sigue viniendo de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.letta. El directorio de configuración debe existir ya. La instalación escribe hooks/herdr-agent-session.sh (hooks/herdr-agent-session.ps1 en Windows) y añade una entrada de Herdr a settings.json. Desinstalar elimina solo la entrada correspondiente y el script gestionado.

Herdr reanuda las conversaciones con nombre con letta --conversation <id>. Registra la conversación por defecto como default:<agent-id> y la reanuda con letta --conversation default --agent <agent-id>.

Cursor Agent CLI

Instala el gancho de Cursor Agent CLI:

herdr integration install cursor

El gancho informa de la identidad de sesión mediante el gancho sessionStart de Cursor mientras Cursor Agent CLI corre en un panel de Herdr. El estado de Cursor viene de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.cursor por defecto, o CURSOR_CONFIG_DIR cuando está definida. El directorio de configuración de Cursor debe existir ya. La instalación escribe herdr-agent-state.sh (herdr-agent-state.ps1 en Windows) y añade una entrada sessionStart de Herdr a hooks.json. Desinstalar elimina la entrada correspondiente y borra el script.

Cuando Cursor emite un evento de inicio de sesión, Herdr puede usar el id informado para reanudar el panel con cursor-agent --resume <id>. El comando cursor-agent debe estar en el PATH cuando Herdr restaure el panel; Herdr no lanza el comando genérico agent.

MastraCode

Instala el gancho de MastraCode:

herdr integration install mastracode

El gancho informa a Herdr del estado de ciclo de vida y de la identidad del hilo de MastraCode, para un estado idle, working y blocked autoritativo y para la restauración nativa. MastraCode no tiene manifiesto de pantalla de respaldo; el estado viene del gancho mientras MastraCode corre en un panel de Herdr.

Herdr usa ~/.mastracode. La instalación escribe hooks/herdr-agent-state.sh (hooks/herdr-agent-state.ps1 en Windows) y añade entradas de comando de Herdr a hooks.json, creando el directorio si no existe. Desinstalar elimina las entradas correspondientes y borra el script.

Herdr reanuda los hilos de MastraCode guardados con mastracode --thread <id>.

Antigravity CLI

Instala el gancho de Antigravity CLI:

herdr integration install antigravity-cli

Herdr usa ~/.gemini/config/ por defecto, o ANTIGRAVITY_CLI_CONFIG_DIR cuando está definida. Es el directorio del que Antigravity CLI lee las personalizaciones globales, y debe existir ya. La instalación escribe hooks/herdr-agent-state.sh (o herdr-agent-state.ps1 en Windows) y añade a hooks.json un bloque herdr propio de Herdr. Antigravity CLI indexa hooks.json por nombre de gancho, así que la instalación reescribe solo ese bloque y no toca los demás. Desinstalar elimina el bloque herdr y borra el script.

Esta integración, solo de sesión, informa de la conversación actual del panel, pero no del estado del agente. Herdr sigue deduciendo trabajando, en espera y bloqueado de lo que Antigravity CLI pinta en pantalla.

El gancho se ejecuta en PreInvocation, así que Herdr conoce la conversación en cuanto se envía el primer prompt. A partir de ahí puede reanudar el panel con agy --conversation <id> tras reiniciar el servidor.

Grok CLI

Instala el gancho de Grok CLI:

herdr integration install grok

El gancho informa de la identidad de sesión mediante el gancho SessionStart de Grok mientras Grok CLI corre en un panel de Herdr. El estado de Grok viene de la detección por manifiesto de pantalla de Herdr.

Herdr usa ~/.grok por defecto, o GROK_HOME cuando está definida. El directorio de configuración de Grok debe existir ya. Grok combina todos los ficheros hooks/*.json de ese directorio, así que la instalación escribe un hooks/herdr.json autónomo con la entrada SessionStart de Herdr junto a hooks/herdr-agent-state.sh (hooks/herdr-agent-state.ps1 en Windows), y nunca edita otros ficheros de ganchos. Desinstalar elimina exactamente esos dos ficheros de Herdr.

Cuando Grok emite un evento de inicio de sesión, Herdr puede usar el id informado para reanudar el panel con grok --resume <id>.

Etiquetas personalizadas de estado

Las integraciones informan del ciclo de vida solo como estado semántico. Por ejemplo, informa de que un agente está working sin añadir campos de presentación al informe de ciclo de vida.

herdr pane report-agent w1:p1 \
  --source custom:docs \
  --agent docs-bot \
  --state working

Los ganchos de usuario que corren junto a una integración gestionada por Herdr deberían usar metadatos en vez de report-agent. Los metadatos cambian la presentación sin quitarle a la integración su autoridad sobre idle, working, blocked ni sobre la restauración de la sesión. --agent y --applies-to-source protegen solo los campos de presentación (--title, --display-agent y --state-label). Los parches de tokens se aplican siempre; quien los informa se encarga de borrarlos o de refrescar su TTL. --display-agent cambia el nombre visible.

herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --token summary="refactor auth" \
  --state-label working="refactoring auth" \
  --ttl-ms 3600000

Los tokens y las etiquetas de estado son solo visuales. Las esperas, las notificaciones y el estado agregado de los espacios de trabajo siguen usando el estado semántico.

Depurar el estado de una integración

Lista los agentes conocidos:

herdr agent list

Lee un panel cuando necesites verificar qué ve Herdr:

herdr pane read w1:p1 --source recent --lines 50

Si el estado de una integración parece incorrecto, confirma primero que el agente corre dentro de Herdr y que el gancho o plugin correspondiente se instaló para la misma cuenta de usuario.