cssgraph

---

¿Por qué cssgraph?

Cuando un agente de IA necesita entender CSS — dónde está definido .btn-primary, qué propiedades tiene, qué selectores en cascada lo afectan, qué componentes JSX lo referencian — descubre el estilo de la manera lenta: grep, glob y Read, un archivo a la vez, reconstruyendo la cascada manualmente.

cssgraph le entrega al agente el contexto de estilo exacto que necesita en una sola llamada. Es un grafo de conocimiento preconstruido de cada className, propiedad CSS, variable y regla-at en tus hojas de estilo — así que en lugar de recorrer archivos, el agente hace una pregunta y obtiene las propiedades, anulaciones, especificidad, llamadores e impacto a nivel de archivo en su totalidad.

---

Instalación

Para Humanos

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

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

O lee la Guía de Instalación, pero en serio, deja que un agente lo haga. Los humanos cometen errores al configurar.

Para Agentes LLM

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

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

---

Inicio Rápido

1. Inicializar

npm i -g cssgraph
cd your-project
cssgraph init --workers 8

Indexa todos los archivos de estilo (CSS, SCSS, Less, Sass), referencias de className en JSX/TSX, CSS-in-JS, CSS Modules, y plantillas de vista (ERB/Haml/HTML) — habilitando cada herramienta MCP.

Pasa --workers <n> para controlar los hilos de parseo paralelo (predeterminado: núcleos de CPU - 1).

Requiere Node.js >= 22.5.0 (para node:sqlite).

2. Conecta tu agente

cssgraph mcp-install

Detecta y configura automáticamente opencode, Claude Code, Cursor, Codex CLI, Gemini CLI, Hermes Agent, Antigravity IDE y Kiro. Escribe la configuración del servidor MCP, el bloque de instrucciones y una Habilidad de Agente (SKILL.md + references/pitfalls.md) que enseña a los agentes cuándo usar cada una de las 13 herramientas de cssgraph, cómo encadenarlas en flujos de trabajo y qué errores evitar.

O agrégalo manualmente a cualquier agente MCP:

{
  "mcpServers": {
    "cssgraph": {
      "type": "stdio",
      "command": "cssgraph",
      "args": ["serve", "--mcp"]
    }
  }
}

3. No más sincronización

La sincronización automática está habilitada por defecto. El servidor MCP observa tu proyecto y actualiza el grafo en cada cambio de archivo — mientras tu agente edita código, o tú agregas/modificas/eliminas archivos CSS. El índice nunca está desactualizado.

---

Cómo Funciona

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "What code files use .btn-primary?"                      │
│      calls cssgraph_rule — one tool call                  │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssgraph MCP Server                       │
│                                                           │
│ rule · O(1) exact selector lookup · loose/strict impact   │
│ explore · properties + overrides + specificity + callers  │
│                             │                             │
│                             ▼                             │
│               SQLite knowledge graph                      │
│     classNames · properties · variables · at-rules        │
│            edges · FTS5 full-text search                  │
└───────────────────────────────────────────────────────────┘

1. Extracción — PostCSS analiza CSS/SCSS/Less/Sass en ASTs. CSS-in-JS (styled.div), referencias de className en JSX y atributos de clase en plantillas extraídos de archivos .jsx/.tsx/.erb/.haml.
2. Almacenamiento — Todo va a una base de datos SQLite local (.cssgraph/cssgraph.db) con búsqueda de texto completo FTS5. Modo WAL + commits por lotes para rendimiento de escritura. Los disparadores FTS e índices únicos se difieren durante la carga masiva por velocidad.
3. Grafo — Las aristas conectan nodos relacionados: contains (selector→propiedad), nests (selector padre→hijo), overrides (selector de mayor especificidad anula a menor), imports (archivo→archivo importado), references (archivo JSX/vista→className, propiedad→variable CSS).
4. Escaneo primero con Git — git ls-files para descubrimiento instantáneo de archivos. Recurre a recorrido del sistema de archivos en proyectos sin git.
5. Parseo paralelo — Los archivos se envían en lotes a hilos de trabajo vía Promise.all. El parseo se completa concurrentemente; los resultados se vacían en orden de archivo para corrección.
6. Auto-Sincronización — Eventos nativos del sistema operativo, con debounce, sincronizados incrementalmente.

---

Referencia CLI

cssgraph init [path] [-w, --workers <n>]  # Initialize + build graph
cssgraph index [path] [-w, --workers <n>]  # Rebuild from scratch
cssgraph query <className>                 # Search for className selectors
cssgraph explore <query...>                # Full style context for a className
cssgraph details <selector>                # O(1) exact selector → file:line lookup
cssgraph rule <selector> [--strict]        # Selector impact: exact + loose/strict files
cssgraph impact-selector <selector>       # Code files affected by a selector
cssgraph impact <className>                # Blast radius of changing a className
cssgraph unused                            # Find unreferenced class selectors
cssgraph cascade <className>               # Visualize cascade path
cssgraph diagnose <className> [chain...]   # Static anchor diagnosis (height/scroll)
cssgraph property <query...>               # Search by CSS property value
cssgraph files [path]                      # Project style file tree
cssgraph status [path]                     # Index statistics
cssgraph sync [path]                       # Incremental update
cssgraph serve --mcp                       # Start MCP server
cssgraph mcp-install                       # Auto-wire to your AI agent (alias: install)
cssgraph skill-install                     # Install/update SKILL.md only (no MCP config changes)
cssgraph skill-uninstall                   # Remove SKILL.md only (no MCP config changes)
cssgraph mcp-uninstall                     # Remove from your AI agent (alias: uninstall)
cssgraph version                           # Print installed version

Escaneo de Archivos JSX y de Vista (predeterminado)

cssgraph siempre escanea:

• JSX/TSX/JS/TS/ES6 — referencias className, CSS-in-JS, CSS Modules
• Plantillas de vista — archivos .erb, .haml, .html para atributos class="..." y la abreviatura .classname de Haml

Esto habilita cssgraph_impact, cssgraph_callers y cssgraph_rule para rastrear tanto archivos de componentes COMO archivos de plantilla que referencian cada className.

Proyecto	Archivos totales	Primer índice	Nodos	Aristas
Pequeño	~50	~15s	~16K	~50K
Monorepo de producción	~11K	~3-5m	~780K	~22M

---

Herramientas MCP

Herramienta	Propósito
cssgraph_explore	PRINCIPAL: Contexto de estilo completo para un className — propiedades, anulaciones, especificidad, llamadores
cssgraph_search	Buscar selectores de className por nombre
cssgraph_callers	Encontrar componentes JSX que referencian un className
cssgraph_impact	Radio de impacto de cambiar un className
cssgraph_rule	Radio de impacto de un selector CSS completo (coincidencia exacta + impacto de archivo suelto/estricto)
cssgraph_impact_selector	Encontrar archivos de código (JS/TS/JSX/TSX) afectados por un selector CSS
cssgraph_details	Búsqueda de selector exacta O(1) (sin aristas, ligera)
cssgraph_unused	Encontrar selectores de clase sin referencias entrantes
cssgraph_cascade	Visualizar la ruta de cascada para un className
cssgraph_diagnose	Diagnóstico de anclaje estático para problemas de scroll/altura — clasifica declaraciones de altura como DEFINIDAS / INDEFINIDAS / NO VERIFICABLES a lo largo de la cadena de ancestros
cssgraph_property	Buscar selectores por valor de propiedad CSS
cssgraph_files	Árbol de archivos de estilo indexado
cssgraph_status	Verificación de salud del índice

---

Herramienta Complementaria: cssprobe-cli

cssgraph es una herramienta de análisis estático — lee tu código fuente y responde dónde está definida una clase, qué cascada la afecta y qué afectaría un cambio. Para preguntas de tiempo de ejecución — qué renderiza realmente una página en un navegador (desbordamiento, cadenas de scroll, cadenas de altura calculadas, secuestros de bloque contenedor) — usa cssprobe-cli, que abre un navegador real y lee estilos calculados más métricas del DOM. Las dos 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 está definida una clase, cascada, impacto, CSS no utilizado	diseño renderizado real, 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 — ve estático primero, 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)
npm i -g cssprobe-cli
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

Instalación: npm install -g cssprobe-cli (requiere Node.js >= 22.5.0). Ver npm / GitHub.

---

Lenguajes Soportados

Lenguaje	Extensión	Extracción
CSS	.css	PostCSS estándar
SCSS	.scss	plugin postcss-scss
Less	.less	plugin postcss-less
Sass (sangrado)	.sass	Compilar → PostCSS
PostCSS personalizado	.pcss	PostCSS estándar
JSX / TSX	.jsx .tsx	className + CSS-in-JS
JavaScript / TypeScript	.js .ts .es6	className + CSS Modules
ERB (Rails)	.erb	extracción class="..."
Haml (Rails)	.haml	extracción .classname + {:class =>}
HTML	.html	extracción class="..."
CSS Modules	.module.css .module.scss .module.less	Resolución de importación dinámica
Tailwind	tailwind.config.js + CSS @theme	Config JS v3 + Config CSS v4

---

Escala de Producción

Proyecto	Archivos totales	Primer índice	Nodos	Aristas
Pequeño	~50	~15s	~16K	~50K
Monorepo de producción	~11K	~3-5m	~780K	~22M

---

Configuración del Proyecto

Cero configuración por defecto. .cssgraph.json opcional en la raíz de tu proyecto:

{
  "exclude": ["static/vendor/", "**/legacy/**"],
  "extensions": {
    ".pcss": "css"
  }
}

Exclusiones predeterminadas integradas (siempre aplicadas): **/*.test.*, **/*.stories.*, **/*.spec.*, **/*.min.*, **/__tests__/**, **/__snapshots__/**, **/__mocks__/**, **/generated/**, **/spec/**, **/vendor/**.

---

Plataformas Soportadas

Plataforma	Arquitecturas	Instalación
macOS	x64, arm64	npm
Linux	x64, arm64	npm
Windows	x64, arm64	npm

---

Si cssgraph es útil

Una estrella ⭐ ayuda a otros desarrolladores a descubrirlo — y nos dice que sigamos publicando.

---

Licencia

MIT