@whenlabs/when

Seis herramientas. Una instalación.

Un kit de herramientas instalable que integra seis herramientas de desarrollo de WhenLabs en tu flujo de trabajo de Claude Code / agente de codificación por IA. Una vez instalado, todas las herramientas están disponibles como herramientas MCP en cada sesión: Claude las utiliza automáticamente cuando es relevante.

Cinco herramientas (stale, envalid, berth, aware, vow) tienen modos de escaneo CLI y se ejecutan según un horario. Velocity es la sexta herramienta: está siempre activa e integrada (respaldada por SQLite), por lo que no tiene un modo de escaneo CLI y no aparece en la salida de doctor/watch/init/ci.

Instalación

npx @whenlabs/when install

Esta es una configuración única. Después de la instalación, las seis herramientas están disponibles en cada proyecto que abras con Claude Code.

Qué hace

Ejecutar npx @whenlabs/when install hará lo siguiente:

Registrará un único servidor MCP (whenlabs) en tu configuración de Claude Code: las seis herramientas, incluida velocity, se sirven desde un solo servidor.
Inyectará instrucciones en CLAUDE.md para que Claude sepa cuándo usar cada herramienta automáticamente, y las preferirá sobre los comandos de shell.
Limpiará cualquier registro heredado de velocity-mcp (velocity ahora está incluido).

Una vez conectado, Claude puede llamar a cualquier herramienta directamente sin que se lo pidas. Por ejemplo, después de una refactorización, Claude podría ejecutar stale_scan para comprobar si hay desfase en la documentación, o antes de una versión, podría ejecutar vow_check para validar las licencias.

Escaneos proactivos en segundo plano

Las herramientas se ejecutan automáticamente en segundo plano según un horario e informan de los hallazgos en la línea de estado de Claude Code:

Herramienta	Intervalo	Línea de estado
berth	15 min	`ports:N` — conflictos de puertos encontrados
stale	30 min	`stale:N` — documentos desfasados respecto al código
envalid	30 min	`env:N` — problemas de validación de .env
vow	60 min	`lic:N?` — licencias desconocidas encontradas
aware	60 min	`aware:stale` — archivos de contexto de IA desactualizados

Solo se muestran los problemas; si todo está limpio, la línea de estado permanece despejada. Cuando Claude ve un problema en la línea de estado, te lo comunica de forma proactiva y se ofrece a solucionarlo.

Herramientas MCP

Estas herramientas están disponibles para Claude en cada sesión después de la instalación:

Herramienta MCP	Qué hace
`velocity_start_task`	Iniciar el cronometraje de una tarea de codificación
`velocity_end_task`	Finalizar el cronometraje y registrar resultados
`velocity_estimate`	Estimar el tiempo para una tarea planificada
`velocity_stats`	Mostrar estadísticas de rendimiento agregadas con información
`velocity_history`	Mostrar el historial de tareas
`stale_scan`	Detectar desfase en la documentación
`stale_fix`	Corregir automáticamente el desfase en la documentación (rutas incorrectas, enlaces muertos, variables de entorno fantasma)
`stale_auto_fix`	Escanear + corregir automáticamente el desfase en una sola llamada
`envalid_validate`	Validar archivos .env frente a esquemas
`envalid_detect`	Encontrar variables de entorno no documentadas en el código base
`envalid_generate_schema`	Generar .env.schema a partir del análisis de código
`envalid_auto_fix`	Detectar variables no documentadas + generar automáticamente entradas de esquema
`berth_status`	Mostrar puertos activos y conflictos
`berth_check`	Escanear el proyecto en busca de conflictos de puertos
`berth_resolve`	Resolver automáticamente conflictos de puertos (terminar o reasignar)
`berth_auto_resolve`	Comprobar + resolver automáticamente conflictos en una sola llamada
`aware_init`	Detectar automáticamente la pila, generar archivos de contexto de IA
`aware_doctor`	Diagnosticar la salud del proyecto y problemas de configuración
`aware_auto_sync`	Diagnosticar + sincronizar automáticamente archivos de contexto de IA desactualizados
`vow_scan`	Escanear y resumir licencias de dependencias
`vow_check`	Validar licencias frente a la política
`vow_hook_install`	Instalar hook de verificación de licencias pre-commit

Esta tabla muestra un subconjunto destacado. Ejecuta when <tool> --help para ver todos los comandos disponibles por herramienta.

Inteligencia entre herramientas

Las herramientas sugieren automáticamente acciones de seguimiento cuando detectan problemas relevantes para otras herramientas. Por ejemplo, aware_init activa un stale_scan cuando genera nuevos archivos, y envalid_detect sugiere berth_register cuando encuentra variables de entorno de URL de servicio. Estas sugerencias en cascada aparecen como líneas "Tip:" en la salida de la herramienta.

Soporte para múltiples editores

Instala servidores MCP en otros editores junto a Claude Code:

npx @whenlabs/when install --cursor     # Cursor
npx @whenlabs/when install --vscode     # VS Code
npx @whenlabs/when install --windsurf   # Windsurf
npx @whenlabs/when install --all        # All supported editors

Sin flags, install apunta solo a Claude Code.

Uso de CLI

También puedes ejecutar herramientas directamente desde la línea de comandos:

when init            # Onboard a project — bootstrap configs, run all tools, auto-fix
when config          # Show unified .whenlabs.yml config
when config init     # Generate .whenlabs.yml from existing tool configs
when config validate # Validate config structure
when stale scan
when stale fix       # Auto-fix documentation drift
when envalid validate
when envalid detect --generate  # Generate schema from code
when berth status
when berth resolve   # Auto-resolve port conflicts
when aware init
when vow scan
when vow hook install  # Install pre-commit license hook
when status          # Show installation status
when doctor          # Run all tools, show unified health report
when doctor --watch  # Continuous monitoring dashboard
when watch           # Background daemon for status line
when ci              # Run checks for CI (exits 1 on issues)

`when init`

Un comando para integrar completamente cualquier proyecto:

Bootstrap — crea .env.schema, .vow.json, .stale.yml y registra puertos berth basados en tu proyecto
Scan — ejecuta las 5 herramientas CLI en paralelo
Auto-fix — corrige automáticamente el desfase si se detecta
Config — genera un .whenlabs.yml unificado a partir de las configuraciones inicializadas

`when config`

Gestiona la configuración unificada del proyecto .whenlabs.yml. Las seis herramientas leen sus ajustes de este único archivo en lugar de archivos de configuración separados. Subcomandos: init (generar a partir de configuraciones existentes), validate (comprobar estructura).

`when doctor`

Ejecuta las 5 herramientas CLI contra el proyecto actual y muestra un informe de salud unificado. Soporta --json para salida legible por máquina y --watch para monitoreo continuo con un panel en vivo.

`when watch`

Demonio en segundo plano que ejecuta las 5 herramientas CLI en intervalos y escribe los resultados en ~/.whenlabs/status.json. Potencia la integración de la línea de estado de Claude Code. Usa --once para un solo escaneo o --interval <seconds> para personalizar el horario.

`when ci`

Ejecuta comprobaciones de stale, envalid y vow; sale con 1 si alguna herramienta encuentra problemas. Diseñado para tuberías de CI:

when ci --ci         # GitHub Actions annotations (::error file=X::message)
when ci --json       # Machine-readable JSON output

GitHub Action

- uses: WhenLabs-org/when@main
  with:
    checks: stale,envalid,vow

Desinstalación

npx @whenlabs/when uninstall

Elimina el servidor MCP y limpia las instrucciones de CLAUDE.md.

Licencia

MIT — ver LICENSE

Creado por Siddharth en WhenLabs

WhenLabs/When