cssgraph

---

Por que cssgraph?

Quando um agente de IA precisa entender CSS — onde .btn-primary está definido, quais propriedades ele possui, quais seletores fazem cascata sobre ele, quais componentes JSX o referenciam — ele descobre o estilo do jeito lento: grep, glob e Read, um arquivo por vez, reconstruindo a cascata manualmente.

cssgraph entrega ao agente o contexto de estilo exato que ele precisa em uma única chamada. É um grafo de conhecimento pré-construído de cada className, propriedade CSS, variável e at-rule em suas folhas de estilo — então, em vez de percorrer arquivos, o agente faz uma pergunta e recebe as propriedades, overrides, especificidade, chamadores e impacto em nível de arquivo por completo.

---

Instalação

Para Humanos

Copie e cole este prompt no seu agente de 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

Ou leia o Guia de Instalação, mas, sério, deixe um agente fazer isso. Humanos erram na configuração.

Para Agentes de LLM

Busque o guia de instalação e siga-o:

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

---

Início Rápido

1. Inicialize

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

Indexa todos os arquivos de estilo (CSS, SCSS, Less, Sass), referências de className em JSX/TSX, CSS-in-JS, CSS Modules, e templates de visualização (ERB/Haml/HTML) — habilitando todas as ferramentas MCP.

Passe --workers <n> para controlar threads de parse paralelas (padrão: núcleos da CPU - 1).

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

2. Conecte seu agente

cssgraph mcp-install

Detecta e configura automaticamente opencode, Claude Code, Cursor, Codex CLI, Gemini CLI, Hermes Agent, Antigravity IDE e Kiro. Escreve a configuração do servidor MCP, bloco de instruções e uma Skill de Agente (SKILL.md + references/pitfalls.md) que ensina agentes quando usar cada uma das 13 ferramentas cssgraph, como encadeá-las em fluxos de trabalho e quais armadilhas evitar.

Ou adicione a qualquer agente MCP manualmente:

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

3. Sem mais sincronização

A sincronização automática está habilitada por padrão. O servidor MCP monitora seu projeto e atualiza o grafo a cada alteração de arquivo — enquanto seu agente edita código, ou você adiciona/modifica/exclui arquivos CSS. O índice nunca fica desatualizado.

---

Como 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. Extração — PostCSS analisa CSS/SCSS/Less/Sass em ASTs. CSS-in-JS (styled.div), referências de className em JSX e atributos de classe em templates extraídos de arquivos .jsx/.tsx/.erb/.haml.
2. Armazenamento — Tudo vai para um banco de dados SQLite local (.cssgraph/cssgraph.db) com busca em texto completo FTS5. Modo WAL + commits em lote para desempenho de escrita. Triggers FTS e índices únicos são adiados durante o carregamento em massa para velocidade.
3. Grafo — Arestas conectam nós relacionados: contains (seletor→propriedade), nests (seletor pai→filho), overrides (seletor de maior especificidade sobrescreve o de menor), imports (arquivo→arquivo importado), references (arquivo JSX/view→className, propriedade→variável CSS).
4. Varredura Git-first — git ls-files para descoberta instantânea de arquivos. Cai para varredura do sistema de arquivos em projetos não-git.
5. Parse paralelo — Arquivos enviados em lotes para threads de trabalho via Promise.all. O parse é concluído concorrentemente; os resultados são liberados na ordem dos arquivos para garantir a correção.
6. Auto-Sincronização — Eventos nativos de arquivo do SO, com debounce, sincronizados incrementalmente.

---

Referência da 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

Varredura de Arquivos JSX e View (padrão)

cssgraph sempre varre:

• JSX/TSX/JS/TS/ES6 — referências className, CSS-in-JS, CSS Modules
• Templates de view — arquivos .erb, .haml, .html para atributos class="..." e abreviação Haml .classname

Isso habilita cssgraph_impact, cssgraph_callers e cssgraph_rule a rastrear tanto arquivos de componentes QUANTO arquivos de template que referenciam cada className.

Projeto	Total de arquivos	Primeiro índice	Nós	Arestas
Pequeno	~50	~15s	~16K	~50K
Monorepo de produção	~11K	~3-5m	~780K	~22M

---

Ferramentas MCP

Ferramenta	Propósito
cssgraph_explore	PRIMÁRIA: Contexto de estilo completo para um className — propriedades, overrides, especificidade, chamadores
cssgraph_search	Buscar seletores de className por nome
cssgraph_callers	Encontrar componentes JSX que referenciam um className
cssgraph_impact	Raio de impacto de alterar um className
cssgraph_rule	Raio de impacto de um seletor CSS completo (correspondência exata + impacto de arquivo flexível/estrito)
cssgraph_impact_selector	Encontrar arquivos de código (JS/TS/JSX/TSX) afetados por um seletor CSS
cssgraph_details	Consulta de seletor exata O(1) (sem arestas, leve)
cssgraph_unused	Encontrar seletores de classe sem referências recebidas
cssgraph_cascade	Visualizar o caminho de cascata para um className
cssgraph_diagnose	Diagnóstico de âncora estática para problemas de rolagem/altura — classifica declarações de altura como DEFINIDAS / INDEFINIDAS / NÃO VERIFICÁVEIS ao longo da cadeia de ancestrais
cssgraph_property	Buscar seletores por valor de propriedade CSS
cssgraph_files	Árvore de arquivos de estilo indexada
cssgraph_status	Verificação de saúde do índice

---

Ferramenta Complementar: cssprobe-cli

cssgraph é uma ferramenta de análise estática — ela lê seu código-fonte e responde onde uma classe está definida, o que faz cascata sobre ela e o que uma alteração afetaria. Para perguntas de tempo de execução — o que uma página realmente renderiza em um navegador (overflow, cadeias de rolagem, cadeias de altura calculada, sequestros de bloco contêiner) — use cssprobe-cli, que abre um navegador real e lê estilos calculados além de métricas de DOM. As duas ferramentas se complementam:

	cssgraph (estático)	cssprobe-cli (tempo de execução)
Analisa	código-fonte (CSS/SCSS/Less + JSX/TSX + templates)	navegador ao vivo (estilos calculados + DOM)
Responde	onde uma classe está definida, cascata, impacto, CSS não utilizado	layout renderizado real, overflow, rolagem, cadeias de altura
Quando	antes/sem um navegador	após análise estática, para verificar em tempo de execução
Uso	cssgraph init + explore/rule/impact	open + inspect/layout/findings

Fluxo de trabalho recomendado para um problema de estilo — vá para o estático primeiro, depois verifique em tempo de execução:

# 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

Instalação: npm install -g cssprobe-cli (requer Node.js >= 22.5.0). Veja npm / GitHub.

---

Linguagens Suportadas

Linguagem	Extensão	Extração
CSS	.css	PostCSS padrão
SCSS	.scss	plugin postcss-scss
Less	.less	plugin postcss-less
Sass (indentado)	.sass	Compilar → PostCSS
PostCSS personalizado	.pcss	PostCSS padrão
JSX / TSX	.jsx .tsx	className + CSS-in-JS
JavaScript / TypeScript	.js .ts .es6	className + CSS Modules
ERB (Rails)	.erb	extração class="..."
Haml (Rails)	.haml	extração .classname + {:class =>}
HTML	.html	extração class="..."
CSS Modules	.module.css .module.scss .module.less	Resolução dinâmica de importação
Tailwind	tailwind.config.js + CSS @theme	Config JS v3 + Config CSS v4

---

Escala de Produção

Projeto	Total de arquivos	Primeiro índice	Nós	Arestas
Pequeno	~50	~15s	~16K	~50K
Monorepo de produção	~11K	~3-5m	~780K	~22M

---

Configuração do Projeto

Zero-configuração por padrão. .cssgraph.json opcional na raiz do seu projeto:

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

Exclusões padrão integradas (sempre aplicadas): **/*.test.*, **/*.stories.*, **/*.spec.*, **/*.min.*, **/__tests__/**, **/__snapshots__/**, **/__mocks__/**, **/generated/**, **/spec/**, **/vendor/**.

---

Plataformas Suportadas

Plataforma	Arquiteturas	Instalação
macOS	x64, arm64	npm
Linux	x64, arm64	npm
Windows	x64, arm64	npm

---

Se cssgraph for útil

Uma ⭐ estrela ajuda outros desenvolvedores a descobri-lo — e nos diz para continuar entregando.

---

Licença

MIT