ccglass: Qué es y Cómo Inspeccionar tus Agentes de IA

Qué hace ccglass

ccglass es un proxy inverso local con registro y panel web que te permite inspeccionar cada solicitud a la API que un agente de codificación envía a un proveedor de modelos de lenguaje. Muchas herramientas (Claude Code, Codex, DeepSeek-TUI, etc.) ignoran los proxies HTTP estándar y no pueden ser interceptadas por mitmproxy ni Charles sin parches frágiles. ccglass funciona sin certificados CA ni problemas de fijado TLS porque el cliente sigue realizando la conexión HTTPS con la API real; solo se intercepta un salto en texto plano hacia localhost.

Puedes ver el prompt completo del sistema, cada esquema de herramientas, el historial completo de mensajes, datos de tokens/caché/costo y un diff entre turnos. Resulta útil para entender qué envía realmente tu agente al modelo, depurar comportamientos relacionados con los prompts y monitorizar el uso y el coste.

Primeros pasos

Requisitos: Node ≥ 18. El proxy central y el panel no tienen dependencias en tiempo de ejecución. La función opcional de autoinspección (MCP) incluye @modelcontextprotocol/sdk y zod solo cuando se usa ccglass claude con herramientas MCP (deshabilítala con --no-mcp).

Instalación global:

npm install -g ccglass

Ejecuta sin argumentos para elegir un cliente de forma interactiva, o indica directamente el nombre del cliente: ccglass claude, ccglass codex, ccglass deepseek, etc. La herramienta inicia un proxy, establece la variable de entorno con la URL base adecuada, lanza el cliente y abre un panel en tu navegador. La salida de ejemplo muestra las URL del proxy y del panel.

Inspeccionar agentes e IDEs

Inicia una inspección para un cliente específico con argumentos opcionales de reenvío: ccglass claude [args...], ccglass codex [args...], y de forma similar para DeepSeek-TUI, Reasonix, Kimi y OpenCode.

Para herramientas arbitrarias, usa el subcomando genérico run:

ccglass run --upstream https://my.custom.api/v1 --env-var MY_CUSTOM_BASE_URL -- my-tool

También puedes reutilizar el formato de un proveedor con --provider. Para extensiones de IDE (Cursor, Cline, Continue) que permiten una URL base de API personalizada, usa ccglass proxy --provider openai o --provider claude. Esto inicia solo el proxy y el panel sin lanzar un proceso hijo. La salida te indica la dirección del proxy que debes configurar en tu IDE y la URL del panel.

Gestionar capturas

Revisa sesiones pasadas con ccglass view. Migra los registros antiguos del proyecto desde ./.ccglass al almacén global con ccglass migrate. Fuerza la migración de capturas existentes al formato v2 con direccionamiento por contenido usando ccglass repack [sesión] (omite la sesión para reempaquetar todas). Elimina una sesión y recupera los blobs huérfanos con ccglass rm <sesión>.

Exporta una sola solicitud en formato raw, Markdown, JSON o HAR:

ccglass export <sesión>/<seq> --format raw|md|json|har

Las capturas se almacenan con direccionamiento por contenido: los mensajes, herramientas y bloques del sistema se escriben una vez en un directorio blobs/ y se referencian por hash, lo que mantiene eficientes las sesiones largas.

Configuración y opciones

Indicadores clave de línea de comandos:

• --provider – fuerza el formato del proveedor para run
• --upstream – anula la URL de la API ascendente
• --port, --proxy-port – puertos del panel y del proxy
• --dir – directorio de registros (por defecto ~/.ccglass/sessions/...)
• --no-open – no abre el panel en el navegador
• --no-mcp – deshabilita las herramientas de autoinspección
• --no-settings-override – no fuerza a Claude Code a usar el proxy
• --no-redact – mantiene los tokens de autenticación sin ocultar
• --env-var – anula la variable de entorno utilizada

Cada proveedor establece una variable de entorno específica: Claude usa ANTHROPIC_BASE_URL, Codex usa OPENAI_BASE_URL, DeepSeek-TUI usa DEEPSEEK_BASE_URL, etc. Pueden requerirse claves adicionales (p. ej., ANTHROPIC_AUTH_TOKEN para Kimi). Los tokens de autenticación están enmascarados por defecto; usa --no-redact para mantenerlos en texto plano. Los registros se almacenan en ~/.ccglass/sessions/<hash-de-ruta-del-proyecto>/<sesión>/NNNN.json, con blobs con direccionamiento por contenido.

Restricciones y limitaciones

• Codex en modo ChatGPT‑login utiliza un transporte WebSocket que elude el proxy; cambia al modo API‑key.
• Los modelos de suscripción integrados en el IDE (p. ej., api2.cursor.sh de Cursor) no pueden ser interceptados; solo funciona el modo BYOK con una URL base personalizada.
• Los endpoints directos de AWS Bedrock fallan porque SigV4 firma el encabezado Host; ccglass imprime una advertencia.
• OpenCode requiere que OPENAI_BASE_URL esté configurado de antemano.
• Para Ollama o LM Studio en direcciones no predeterminadas, pasa --upstream para apuntar al host:puerto correcto.

Prácticas recomendadas

• Ejecuta ccglass migrate cuando se te solicite para mover registros antiguos al almacén global.
• Mantén --no-redact desactivado para evitar la fuga de tokens de autenticación.
• Usa ccglass view para revisar sesiones pasadas sin volver a iniciar el agente.
• Exporta solicitudes para documentación o depuración con --format.
• Al usar la función MCP de autoinspección con Claude Code, mantenla habilitada a menos que no la necesites.
• Si un selector de proveedor ya establece ANTHROPIC_BASE_URL, pasa --no-settings-override para evitar anulaciones duplicadas.
• Trata el directorio de registros como sensible independientemente de la redacción.