cssprobe-cli

cssprobe-cli

Sonda CSS en tiempo de ejecución: inspecciona diseño, scroll, colores, fondos, fuentes y más en un navegador en vivo. Diseñado tanto para humanos como para agentes de IA.

Diagnóstico CSS estático y en tiempo de ejecución para agentes de IA: combínalo con cssgraph (el grafo de conocimiento CSS) para tener el panorama completo.

---

¿Por qué cssprobe-cli?

Cuando un agente de IA necesita depurar CSS — por qué este elemento se desborda, cuál es el diseño real renderizado, si este contenedor es desplazable — no puede ver el navegador. Adivina a partir del código estático, perdiéndose problemas que solo aparecen en tiempo de ejecución, como desbordamientos, cadenas de scroll y secuestros del bloque contenedor.

cssprobe-cli le da ojos al agente. Abre un navegador real, recopila estilos calculados y métricas mediante JavaScript inyectado, los analiza con un modelo de confianza y devuelve hallazgos estructurados, todo en un solo comando. El agente hace una pregunta sobre cualquier selector y obtiene el árbol DOM, el diagrama de diseño ASCII, las advertencias de desbordamiento y el diagnóstico de scroll sin salir de la terminal.

---

Instalación

Para humanos

Copia y pega este prompt en tu agente LLM (Claude Code, Cursor, Codex, etc.):

Install and configure cssprobe-cli by following the instructions here:
https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

O lee la Guía de instalación, pero en serio, deja que un agente lo haga. Los humanos cometemos errores al escribir configuraciones.

Para agentes LLM

Obtén la guía de instalación y síguela:

curl -s https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

O instala directamente:

npm install -g cssprobe-cli
cssprobe-cli skill-install

---

Cómo funciona

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "Is .sidebar overflowing?"                               │
│      calls: cssprobe-cli inspect .sidebar                 │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssprobe-cli daemon                       │
│                                                           │
│  collector (IIFE) → analyzer (pure) → renderer (md/json)  │
│                             │                             │
│                             ▼                             │
│               Playwright browser (Chromium)                │
│     getBoundingClientRect · getComputedStyle · DOM walk    │
└───────────────────────────────────────────────────────────┘

1. Sesión — open inicia un proceso demonio que gestiona un navegador. Los comandos se conectan mediante un socket Unix.
2. Recopilador — Se inyecta como IIFE en la página. Recorre el DOM, lee estilos calculados, valores declarados y métricas de elementos.
3. Analizador — Funciones puras de Node.js. Clasifica los hallazgos con niveles de confianza (DEFINIDO / INDEFINIDO / NO VERIFICABLE).
4. Renderizador — Genera salida en Markdown (por defecto) o JSON. Incluye diagrama de diseño ASCII, árbol DOM y hallazgos.

---

Inicio rápido

1. Inspeccionar una página

# Open browser (non-blocking, starts daemon session)
cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout

# Inspect with CSS selector
cssprobe-cli inspect .container

# Show ASCII layout diagram
cssprobe-cli layout .container

# Show only issues/warnings
cssprobe-cli findings .container

# Close browser when done
cssprobe-cli close

2. Páginas protegidas con inicio de sesión

# Open browser in headed mode
cssprobe-cli open https://mysite.com --headed

# User manually logs in...

# Save session state for future use
cssprobe-cli state-save --name mysite

# Reopen with saved state (no login needed)
cssprobe-cli open https://mysite.com --state state.json --headed

3. Salida JSON

cssprobe-cli inspect body --json
cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'

4. Uso como servidor MCP (clientes de IA)

cssprobe-cli incluye un servidor MCP (stdio), por lo que los clientes de IA lo llaman como una herramienta nativa, sin necesidad de shell:

cssprobe-cli mcp-install          # auto-detect and configure installed clients
cssprobe-cli mcp-install --target=claude,cursor,codex
cssprobe-cli mcp-install --local  # write project-scoped config

Configuración manual para cualquier cliente MCP:

{
  "mcpServers": {
    "cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
  }
}

Expone 10 herramientas: cssprobe_open, cssprobe_inspect, cssprobe_tree, cssprobe_layout, cssprobe_findings, cssprobe_eval, cssprobe_screenshot, cssprobe_inject_css, cssprobe_close, cssprobe_status. Elimínalas con cssprobe-cli mcp-uninstall.

---

Comandos

Gestión de sesiones

Comando	Descripción
open [url]	Abre el navegador en modo sesión (sin bloqueo)
open [url] --headed	Muestra la ventana del navegador
open [url] --state <file>	Abre con cookies y localStorage guardados
open [url] --viewport 1280x720	Tamaño de viewport personalizado
close	Cierra la sesión del navegador
close --all	Cierra todas las sesiones en todos los espacios de trabajo
status	Muestra el estado de la sesión

Inspección CSS

Comando	Descripción
inspect <selector>	Diagnóstico CSS completo (valores calculados, valores declarados, hallazgos)
inspect <selector> --layout	Incluye diagrama de diseño ASCII
inspect <selector> --brief	Compacto: solo esquema del árbol + advertencias/errores
inspect <selector> --json	Salida JSON estructurada
tree <selector>	Estructura del árbol DOM
layout <selector>	Diagrama de diseño ASCII
findings <selector>	Solo problemas/advertencias/errores

Inyección CSS

Comando	Descripción
inject-css <css>	Inyecta CSS en la página actual

Navegador

Comando	Descripción
resize <width> <height>	Redimensiona el viewport del navegador
eval <expression>	Evalúa JavaScript (contexto del navegador)
playwright <call>	Ejecuta la API de Playwright (contexto Node.js)
screenshot	Toma una captura de pantalla (se guarda en ~/.cssprobe-cli/screenshots/, usa --out para sobrescribir)

Estado

Comando	Descripción
state-import <file>	Importa cookies desde formato Netscape
state-save	Guarda el estado actual de la sesión del navegador (cookies + localStorage)

Configuración

Comando	Descripción
config-show	Muestra la configuración actual
config-set <key> <value>	Establece un valor de configuración
config-list	Lista todos los perfiles
config-use <name>	Cambia el perfil activo
config-new <name>	Crea un nuevo perfil
config-path	Muestra la ruta del archivo de configuración

---

Modelo de confianza

Cada hallazgo lleva un nivel de confianza:

Nivel	Significado
DEFINIDO	Basado en valores calculados (hechos de getComputedStyle) o valores declarados accesibles
INDEFINIDO	El valor declarado usa % — se resuelve en tiempo de ejecución
NO VERIFICABLE	Valor declarado ausente o proveniente de una hoja de estilos de origen cruzado bloqueada

El encabezado del informe muestra: confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1

---

Herramienta complementaria: cssgraph

cssprobe-cli es una sonda CSS de tiempo de ejecución — abre un navegador real y lee lo que realmente se renderiza. Para preguntas estáticas sobre el código fuente — dónde se define .btn-primary, qué cascada lo afecta, qué componentes lo referencian, qué cambiaría si lo edito — usa cssgraph, un grafo de conocimiento SQLite local de cada className, propiedad, variable y regla-at en tus hojas de estilo. Ambas herramientas se complementan:

	cssgraph (estático)	cssprobe-cli (tiempo de ejecución)
Analiza	código fuente (CSS/SCSS/Less + JSX/TSX + plantillas)	navegador en vivo (estilos calculados + DOM)
Responde	dónde se define una clase, cascada, impacto, CSS no utilizado	diseño real renderizado, desbordamiento, scroll, cadenas de altura
Cuándo	antes/sin navegador	después del análisis estático, para verificar en tiempo de ejecución
Uso	cssgraph init + explore/rule/impact	open + inspect/layout/findings

Flujo de trabajo recomendado para un problema de estilo — primero lo estático, luego verifica en tiempo de ejecución:

# 1. Static: find the definitions, cascade, and blast radius (cssgraph)
cssgraph explore .btn-primary
cssgraph cascade .btn-primary

# 2. Runtime: confirm what actually renders (cssprobe-cli)
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

Instalación: npm install -g cssgraph (requiere Node.js >= 22.5.0). Expone 12 herramientas MCP (cssgraph_explore, cssgraph_rule, cssgraph_impact, …) además de comandos CLI. Consulta npm / GitHub.

---

Configuración

# Set values
cssprobe-cli config-set browser chromium
cssprobe-cli config-set depth 8
cssprobe-cli config-set viewport 375x812

# Profile management
cssprobe-cli config-new staging
cssprobe-cli -p staging config-set browser firefox
cssprobe-cli config-use staging

Prioridad: Banderas CLI > Variables de entorno > Archivo de configuración

--browser       CSSPROBE_BROWSER
--depth         CSSPROBE_DEPTH
--headed        CSSPROBE_HEADED
--viewport      CSSPROBE_VIEWPORT
-p, --profile   CSSPROBE_PROFILE

Archivo de configuración: ~/.cssprobe-clirc

---

Plataformas compatibles

Plataforma	Arquitecturas
macOS	x64, arm64
Linux	x64, arm64
Windows	x64, arm64

---

Desarrollo

npm install
npm run build       # tsc + esbuild collector + daemon entry + generate help.json
npm test            # Run unit tests (58 tests)
npx tsc --noEmit    # Type check only

Si cssprobe-cli te resulta útil

Una ⭐ estrella ayuda a que otros desarrolladores lo descubran — y nos indica que sigamos publicando.

---

Licencia

MIT