Creé una extensión Raycast para monitorear Claude Code

Era otra tarde cualquiera.

Tenía 5 sesiones de Claude Code ejecutándose simultáneamente en la terminal: una modificando el blog, otra escribiendo endpoints del backend, otra revisando código, y las dos restantes... ni idea de en qué paso estaban. Iba saltando de una a otra sin poder distinguir cuál esperaba mi input, cuál seguía trabajando y cuál ya había terminado.

"Ojalá existiera un lugar donde pudiera ver el estado de todas las sesiones de un vistazo."

Busqué por todos lados. Hay algunas herramientas para monitorear Claude Code, pero ninguna cumplía del todo con lo que necesitaba. No solo quería ver el estado de las sesiones, necesitaba un lugar unificado para gestionar todo lo relacionado con Claude Code: sesiones, Skills, servidores MCP, plugins. Y sin importar desde qué terminal o editor hubiera abierto una sesión, poder saltar directamente a ella con un clic.

Si no existe, lo construyo yo.

La era de la IA: si lo quieres, hazlo tú mismo

La mayor revelación de estos últimos años es que la IA ha eliminado por completo la distancia entre "querer una herramienta" y "tener una herramienta".

Antes, si tenías una idea, o esperabas a que alguien la implementara, o te pasabas meses aprendiendo un framework nuevo para construirla desde cero. La mayoría de las ideas terminaban en un "bueno, me conformo con lo que hay".

Ahora es diferente. Solo necesitas describir claramente lo que necesitas, y Claude Code se encarga del resto.

Visitar

Ya había creado dos extensiones de Raycast con IA, así que cuando surgió esta nueva necesidad, me puse manos a la obra de forma natural: desde la primera línea de código hasta tener la funcionalidad básica completa, fue cuestión de una sola noche.

Si aún no conoces Raycast, puedes leer mi artículo anterior 《Raycast: mi aplicación favorita de Mac》. En pocas palabras, es el centro de productividad en macOS; prácticamente todas mis operaciones frecuentes pasan por ahí. Por eso, cuando quise crear una herramienta de monitoreo para Claude Code, Raycast fue la elección más natural: soporta iconos permanentes en la barra de menú, operación prioritaria por teclado y rendimiento nativo de macOS, perfecto para el caso de uso de "echar un vistazo rápido".

En la era de la IA, no necesitas esperar a que alguien lo haga: tú eres ese alguien.

Puntos de dolor: por qué necesitaba esta herramienta

Cuanto más usas Claude Code, más pequeñas fricciones se acumulan. Individualmente no parecen gran cosa, pero en conjunto consumen atención todos los días.

El estado de múltiples sesiones es invisible, y volver a ellas es un dolor

Este es el punto de dolor más directo. Claude Code se ejecuta en la terminal, una ventana por sesión. Es normal tener varios proyectos abiertos a la vez: el blog ajustando estilos, un plugin añadiendo funcionalidades, una librería corrigiendo bugs. Pero el problema es que no puedes ver qué sesión espera tu input, cuál sigue ejecutándose y cuál ya terminó.

Lo más frustrante es la navegación. La sesión del blog está en Zed, la del plugin corriendo en Warp, y hay otra sesión de una librería en segundo plano. ¿Quieres volver a alguna? Primero tienes que recordar en qué ventana está cada proyecto, y luego buscar entre un montón de terminales. Lo que necesito es: sin importar desde dónde se abrió la sesión, poder saltar directamente a ella con un clic.

Sin percepción del consumo de tokens

Programando con Claude Code todos los días, los tokens no paran de correr. La CLI tiene un comando /cost, pero para usuarios con suscripción solo dice "estás usando tu cuota de suscripción", sin mostrar cifras concretas. ¿Qué proyecto consume más? ¿Cómo se compara el consumo de hoy con el de ayer? ¿Cómo se distribuye el gasto entre modelos? Sin respuesta alguna.

Actualizar y gestionar plugins es engorroso

El ecosistema de plugins de Claude Code es cada vez más rico; tengo más de una docena instalados. Pero gestionarlos es muy primitivo: para ver qué plugins tienes, sus versiones o si hay actualizaciones, hay que ir a revisar archivos de configuración. Activar, desactivar, actualizar, desinstalar... cada paso requiere operaciones en línea de comandos.

Lo más desesperante es la experiencia de actualización. Actualizas un plugin con esfuerzo, y la próxima vez que inicias Claude Code descubres que volvió a la versión anterior. La línea de comandos te dice "actualización exitosa", pero no puedes confirmar si realmente se actualizó: sin comparación de versiones, sin changelog, sin ningún lugar donde ver las versiones actuales de todos los plugins. Con muchos plugins, la gestión se convierte en trabajo manual basado puramente en la memoria.

El estado de Skills y servidores MCP es desconocido

Después de instalar un Skill, ¿cómo confirmas que realmente está funcionando? ¿Es a nivel de usuario o de proyecto? ¿Desde qué plugin se instaló? Más problemático aún son los servidores MCP: configuras cinco o seis, pero no sabes cuál está conectado, cuál necesita reautenticación y cuál simplemente no conecta. Esta información está dispersa en diferentes archivos de configuración, sin un lugar unificado para ver el panorama completo.

En resumen, necesitaba un panel de control: ver de un vistazo el estado de todas las sesiones, la distribución del consumo y la salud de las extensiones.

Proceso de desarrollo

Paso 1: Escribir el PRD, definir los requisitos claramente

Al programar con IA, el paso más importante no es escribir código, sino tener claros los requisitos.

Primero le pedí a Claude Code que me ayudara a escribir un PRD (Documento de Requisitos del Producto), listando una por una todas las funciones que quería: monitoreo de sesiones en tiempo real, estado permanente en la barra de menú, panel de estadísticas de consumo, gestión de extensiones (Plugins + Skills + MCP Servers), y navegación/restauración con un clic. Las interacciones esperadas de cada función, de dónde vienen los datos y cómo se muestran, todo quedó documentado en el PRD.

Una vez listo el PRD, la implementación avanzó módulo por módulo según el documento, y Claude Code prácticamente no necesitó que le explicara más contexto.

Paso 2: Investigar soluciones existentes

Con el PRD definido, le pedí a Claude Code que investigara: ¿qué herramientas open source para monitorear Claude Code ya existen? ¿Cómo están implementadas?

La investigación reveló que la mayoría de las soluciones existentes se basan en leer archivos JSONL. Claude Code escribe en tiempo real los registros de cada sesión en archivos .jsonl dentro del directorio ~/.claude/projects/, incluyendo la cantidad de tokens de cada turno de conversación, el modelo usado, timestamps, etc. Parseando estos archivos se pueden reconstruir los datos detallados de cada sesión.

Los datos JSONL son muy ricos, pero son más adecuados para análisis estadístico: acumulación de tokens, distribución por modelos, comparaciones entre proyectos. Para el seguimiento en tiempo real del estado de las sesiones (quién espera input, quién está ejecutándose), se necesita otra fuente de datos.

Ahí entra la Claude Code Hooks API. Los Hooks son un mecanismo oficial de eventos del ciclo de vida de Claude Code, que permite registrar scripts que se ejecutan automáticamente en eventos como SessionStart, UserPromptSubmit, PreToolUse, Stop, SessionEnd y Notification. Ya había usado Hooks con Claude Code antes, sabía que podían hacer seguimiento de estado basado en eventos.

La idea quedó clara: Hooks para el estado en tiempo real, JSONL para los metadatos enriquecidos. Las dos fuentes de datos se complementan para construir una solución de monitoreo completa.

¿Y por qué elegir Raycast en lugar de un panel web o una extensión de VS Code? Simple: Raycast ya es mi centro de productividad, soporta iconos permanentes en la barra de menú y puedo echar un vistazo al estado sin abrir ninguna ventana. Las operaciones por teclado son fluidas y no interrumpen el flujo de trabajo. Además, el desarrollo de extensiones de Raycast usa React + TypeScript, tecnologías que domino perfectamente.

Paso 3: Una noche para hacerlo funcionar

Con el PRD y la solución técnica listos, el resto fue dejar que Claude Code lo implementara. El flujo de datos del sistema tiene dos líneas:

Eventos del ciclo de vida de Claude Code
        │
        ▼
    hook.sh (Bash + Python embebido)
        │
        ├── Bloqueo atómico de archivos (mkdir)
        ├── Mapeo evento → estado
        ├── Generación asíncrona de etiquetas IA (Haiku)
        └── Limpieza de sesiones expiradas
        │
        ▼
    sessions.json (estado en tiempo real)
        │
        └──────────┐
                   ▼
        Raycast Extension
          useSessions Hook
                   ▲
        ┌──────────┘
        │
    ~/.claude/projects/**/*.jsonl
        │
        └── Parseo regex basado en chunks
            (256KB de memoria fija)

En resumen: los Hooks capturan eventos en tiempo real y los escriben en sessions.json, el parseo JSONL proporciona metadatos de tokens y modelos, y la extensión de Raycast fusiona ambos para mostrarlos. Los detalles técnicos (bloqueo atómico de archivos, parseo regex por chunks, generación de etiquetas IA, caché en disco) fueron decisiones de Claude Code; yo solo me encargué de verificar que funcionara.

Lo realmente interesante fue la fase de depuración. Usar la propia herramienta que estás construyendo para monitorear Claude Code, y descubrir y corregir problemas continuamente:

• Subagentes inundaron el panel: nada más arrancar, aparecieron un montón de sesiones desconocidas en la lista. Investigando durante un buen rato descubrí que los subagentes de Claude Code también disparaban los Hooks: una sesión principal lanzaba una docena de subagentes y el panel explotaba. Se solucionó añadiendo un filtro.
• Falsas alertas de MCP: la página de Extensions mostraba varios MCP como "Unreachable", pero en realidad funcionaban perfectamente. Resulta que los MCP en modo stdio no deberían recibir health checks HTTP.
• Worktrees no reconocidos: al principio no detectaba sesiones en worktrees. Se solucionó añadiendo una expresión regular para la ruta .claude/worktrees/.
• Actualizaciones de plugins falsas: al desarrollar la gestión de extensiones descubrí un bug de Claude Code: al actualizar plugins, la CLI no hacía pull del repositorio remoto primero, sino que comparaba directamente con la caché local, mostrando siempre "ya está actualizado". En la extensión añadí un paso previo de git pull manual al repositorio marketplace para que las actualizaciones realmente funcionaran.

Así fue el ciclo: "usar → encontrar problemas → hacer que Claude Code los corrija → seguir usando". Usé Claude Code para construir una herramienta que monitorea Claude Code, y luego usé esa herramienta para monitorear al Claude Code que la estaba construyendo. Recursión pura.

Paso 4: Crear el icono

En todo el proceso de desarrollo, lo único que tuve que hacer manualmente fue crear el icono.

Busqué en iconfont y me enamoré al instante del cangrejito de Claude Code, un diseño inconfundible:

Después usé la herramienta oficial Icon Maker de Raycast, elegí los colores y el estilo, y generé el icono final de la extensión:

Aparte de este paso, desde escribir código hasta enviarlo a la Raycast Store, todo lo hizo Claude Code. No modifiqué ni una sola línea de código manualmente.

Demostración de funciones

Monitoreo de sesiones

Esta es la función principal de la extensión. Al abrir Claude Code Sessions, todas las sesiones aparecen agrupadas por estado: Active (ejecutándose), Waiting for Input (esperando tu input), Idle (inactiva), Ended (finalizada).

Cada sesión muestra: nombre del proyecto, etiqueta generada por IA, tipo de editor/terminal, rama de Git, duración. Si la sesión se ejecuta en un Git worktree, también muestra una insignia de worktree.

Selecciona cualquier sesión y pulsa Enter para saltar directamente a la ventana del editor correspondiente (compatible con VS Code, Cursor, Zed, Windsurf) o terminal (Terminal, iTerm2, Warp, Ghostty, kitty). Las sesiones finalizadas se pueden reanudar con un clic, sin necesidad de escribir manualmente claude --resume.

Presencia permanente en la barra de menú

Claude Code Status es un icono en la barra de menú que muestra constantemente el número de sesiones activas. El color cambia según el estado: verde indica que hay sesiones ejecutándose, naranja que alguna espera tu input, amarillo que todas están inactivas.

Al hacer clic en el icono se despliega un menú donde puedes ver el nombre del proyecto, tipo de terminal, duración y estado de todas las sesiones. Haz clic en cualquiera para navegar directamente.

Esto resolvió mi mayor punto de dolor: ya no necesito recorrer ventanas de terminal una por una. Con un vistazo a la barra de menú, las naranjas están esperándome, las verdes están trabajando, y las demás las puedo ignorar.

Además, con esta barra de estado, inconscientemente quieres mantenerla siempre en verde, es decir, que siempre haya sesiones ejecutándose, siempre haya trabajo en marcha. Cuando todo se pone amarillo, enseguida asignas otra tarea. Básicamente, se trata de exprimir a Claude Code al máximo, sin dejarlo descansar ni un minuto.

Panel de consumo

Claude Code Usage ofrece estadísticas completas del consumo de tokens. En la parte superior hay una tabla resumen: cuántos tokens se usaron hoy, esta semana y este mes, y cuántas sesiones se ejecutaron.

Debajo, un gráfico de tendencia diaria (últimos 7 días), consumo clasificado por modelo (Opus vs Sonnet vs Haiku), y un ranking de consumo por proyecto: por fin puedes ver qué proyecto consume más tokens.

Ahora reviso este panel de vez en cuando para entender el consumo de tokens de cada proyecto. Cuando detecto que un proyecto tiene un consumo anormalmente alto, puedo ajustar la estrategia a tiempo, por ejemplo, cambiar algunas tareas simples de Opus a Sonnet.

Gestión de extensiones

Claude Code Extensions unifica Plugins, Skills y MCP Servers en una sola interfaz.

La página de Plugins lista todos los plugins instalados, mostrando estado de activación/desactivación, número de versión y repositorio de origen. Puedes activar, desactivar, actualizar y desinstalar con un clic, además de ver los commands, skills, agents y MCP servers que incluye cada plugin.

La página de MCP Servers muestra todos los servidores MCP configurados y su estado de conexión: Connected (conectado), Needs Auth (necesita autenticación), Unreachable (inalcanzable). Para los servidores que necesitan autenticación, puedes abrir directamente el enlace de autenticación para completar la autorización.

Se acabó el adivinar "¿este MCP estará conectado o no?".

Un pequeño incidente: me banearon la cuenta

Durante el desarrollo surgió un contratiempo inesperado.

La extensión tiene una función que genera automáticamente etiquetas para cada sesión, usando las capacidades de IA integradas de Raycast. Durante las pruebas, tenía varias sesiones de Claude Code abiertas simultáneamente, y cada sesión al iniciarse llamaba una vez a Raycast AI para generar la etiqueta. En poco tiempo, el volumen de solicitudes se disparó.

Un día abrí Raycast y no pude iniciar sesión. Ni por email, ni por GitHub.

La notificación de baneo sonaba aterradora: baneo permanente, violación de los términos de servicio secciones IV, VI, VIII, "abuso de IA", sin posibilidad de restauración.

Me quedé en shock. Ni siquiera había tenido tiempo de gastar mis 200 dólares de crédito de Claude, ¿qué abuso?

Fui corriendo a la comunidad de Slack de Raycast a apelar, pegué el enlace del repositorio de GitHub y les dije: miren el código, es un plugin normal de monitoreo de Claude Code, las llamadas a IA son parte de la funcionalidad del plugin, no es ningún abuso.

Resultó que era fin de semana y el equipo de Raycast no trabajaba. Esperé dos días hasta que el lunes Tirta respondió. Afortunadamente fue muy amable y se disculpó directamente, explicando que su sistema de detección automática había clasificado erróneamente las llamadas legítimas de alta frecuencia del plugin como comportamiento abusivo. Este patrón de uso impulsado por extensiones no lo habían contemplado; era culpa suya. Mi cuenta fue restaurada de inmediato.

Un buen susto. Aunque, viéndolo desde otro ángulo, también demuestra que el plugin realmente estaba trabajando duro, tanto que hasta confundió a la plataforma.

Reflexión final

Desde la idea inicial ("ojalá pudiera ver el estado de todas las sesiones") hasta lo que es hoy Claude Code Monitor, la funcionalidad principal se completó en una sola noche. Esta es la experiencia real del desarrollo asistido por IA: una herramienta completa con monitoreo de sesiones, estadísticas de consumo, gestión de extensiones y presencia permanente en la barra de menú, de la idea al producto funcional, más rápido de lo que podría haber imaginado.

Este es el regalo que la era de la IA ofrece a los desarrolladores comunes: tu frontera de productividad ya no la define qué tecnologías dominas, sino qué problemas quieres resolver.

El proyecto es open source, con licencia MIT. Bienvenidos a usarlo y contribuir:

GitHub: wuyuxiangX/claude-code-monitor

Si tú también eres un usuario intensivo de Claude Code, dale una oportunidad. Y si no se ajusta completamente a tus necesidades, no te preocupes: construye el tuyo propio. Ahora tienes la capacidad para hacerlo.