Plugin para Claude Code

El plugin de Hilbana para Claude Code es la vía más corta para trabajar con Hilbana desde tu propio repositorio: con una sola instalación quedan conectados el servidor MCP, la memoria por proyecto, la contabilidad de tokens por tarea y los comandos del ciclo (/hilbana-claim-next, /hilbana-finish, …).

Se instala desde su marketplace público: github.com/hilbana/claude-plugin. Si prefieres el por qué antes del cómo, lo contamos en el blog: tus agentes dejan de empezar de cero.

Qué vía te conviene

Hay tres formas de conectar Hilbana con Claude, y no compiten: cada una es para un sitio distinto.

• Plugin (esta página): para Claude Code, trabajando dentro de tu repo. Es la única que trae memoria automática, comandos del ciclo y medición del gasto.
• Conector: para claude.ai (web y escritorio), con OAuth y sin gestionar ninguna clave. Para consultar y operar tú mismo.
• Clave de API: para agentes propios y servicios o entornos headless / CI, donde registras el MCP a mano con un Bearer hil_….

Requisitos

• Claude Code instalado.
• Node 18+ en el PATH. Los hooks se ejecutan con node, y el de cierre de sesión usa el fetch global (disponible desde Node 18). Sin Node los hooks simplemente no corren: la sesión funciona igual, pero pierdes la memoria automática y la contabilidad de tokens.

Instalación

En Claude Code, añade el marketplace e instala el plugin:

/plugin marketplace add hilbana/claude-plugin
/plugin install hilbana@hilbana

Después reinicia Claude Code (o lanza /reload-plugins).

Configuración

Al instalar, Claude Code te pide dos datos:

• api_key (obligatoria): se crea en Ajustes → API keys de cualquier workspace del que seas miembro. El formato es hil_…. La clave te identifica a ti: alcanza todos tus workspaces y ese es solo el de por defecto, el que se usa cuando no se indica otro (ver API y MCP). Se guarda solo en tu configuración local y está marcada como sensible.
• base_url (opcional): déjala vacía para usar https://app.hilbana.com. Solo hace falta si tienes una instalación propia, y va sin /mcp al final (el plugin lo añade él).

Qué trae

Servidor MCP auto-registrado. No hay que ejecutar ningún claude mcp add: el plugin declara el servidor y lo autentica con tu clave.

Memoria por proyecto. Un hook de SessionStart recuerda al agente que cargue el contexto previo al abrir el repo, y otro de SessionEnd guarda un resumen al cerrar. El ámbito es el nombre de la carpeta del repositorio, así que funciona en cualquier repo, no solo en los que tienes como proyecto en Hilbana. Ver Memoria de agentes.

Contabilidad de tokens por tarea. Los hooks Stop y SessionEnd calculan el gasto real leyendo la transcripción y lo reportan solos. El servidor lo imputa a la issue que el agente tenga reclamada en ese momento; sin reclamo queda registrado como consumo no imputado. Es deliberado que lo mida el hook y no el agente: un modelo no sabe lo que consume, y si se le pregunta, se lo inventa.

Comandos del ciclo. Implementan el modelo pull del framework de trabajo: el tracker es la cola y el trabajador tira de ella.

Comando	Para qué
/hilbana-claim-next	Coge la siguiente issue lista para agente y la arranca.
/hilbana-finish	Cierra tu turno en In Review, con verificación, telemetría y memoria.
/hilbana-review	Revisa lo que está en In Review: aprueba a Done o lo devuelve.
/hilbana-plan	Convierte un objetivo en un grafo de sub-issues y encola la frontera.
/hilbana-trabajar-issue	Trabaja una issue concreta de principio a fin.
/hilbana-crear-docs	Arranca la documentación de un proyecto desde tu repo.
/hilbana-memoria-switch	Migra tu memoria de agente desde engram a Hilbana.

Regla del ciclo: un trabajador nunca cierra su propio trabajo a Done, se para en In Review. Quien revisa es quien cierra.

Skills. hilbana-memoria (el protocolo de memoria) y hilbana-mcp (las herramientas MCP y los flujos de la cola). No se invocan: se cargan solas cuando hacen falta.

Verificar que funciona

1. /plugin list → hilbana aparece habilitado.
2. En una sesión nueva, comprueba que existen las herramientas de memoria. Instaladas como plugin llevan el prefijo del espacio de nombres: mcp__plugin_hilbana_hilbana__mem_*.
3. Prueba de humo: pídele «carga el contexto de memoria». El agente debe llamar a mem_context con el ámbito del repo actual.

Actualizar

Las versiones se publican como releases del repositorio. Claude Code no avisa por su cuenta: solo muestra que hay actualización cuando abres /plugin. Para no perdértelas, pon el repo en Watch → Custom → Releases.

/plugin marketplace update hilbana
/plugin install hilbana@hilbana

Y reinicia Claude Code.

Problemas comunes

El plugin no aparece. Casi siempre falta reiniciar Claude Code después de instalar, o el marketplace no se añadió (repite /plugin marketplace add).

Las herramientas no ven tus issues. Los listados usan el workspace por defecto de la clave. Si las issues están en otro del que también eres miembro, pásale workspaceId (lo da list_workspaces) o usa una clave creada en ese workspace. Si no eres miembro, no hay nada que ajustar: te tienen que invitar.

El MCP no conecta. Revisa que base_url no lleve /mcp al final. El plugin lo añade, así que con https://app.hilbana.com/mcp la URL final queda duplicada.

No se guarda memoria ni se registra el gasto. Falta Node 18+ en el PATH. Los hooks fallan en silencio a propósito, para no romperte la sesión.

Relacionado: Prompts · Conectar con Claude · API y MCP · Agentes · Memoria de agentes.