cssprobe-cli

cssprobe-cli

Sonda CSS em tempo de execução — inspecione layout, rolagem, cores, fundos, fontes e muito mais em um navegador ao vivo. Feito para humanos e agentes de IA.

Diagnóstico de CSS estático + em tempo de execução para agentes de IA — combine com cssgraph (o grafo de conhecimento CSS) para ter o panorama completo.

---

Por que cssprobe-cli?

Quando um agente de IA precisa depurar CSS — por que este elemento está estourando, qual é o layout realmente renderizado, este contêiner é rolável — ele não consegue ver o navegador. Ele adivinha a partir do código estático, perdendo problemas que só aparecem em tempo de execução, como overflow, cadeias de rolagem e sequestros de bloco contêiner.

cssprobe-cli dá olhos ao agente. Ele abre um navegador real, coleta estilos computados e métricas via JavaScript injetado, analisa-os com um modelo de confiança e retorna descobertas estruturadas — tudo em um único comando. O agente faz uma pergunta sobre qualquer seletor e recebe a árvore DOM, diagrama de layout ASCII, avisos de overflow e diagnóstico de rolagem sem sair do terminal.

---

Instalação

Para Humanos

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

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/cssprobe-cli/main/docs/guide/installation.md

Ou instale diretamente:

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

---

Como 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. Sessão — open inicia um processo daemon que gerencia um navegador. Os comandos se conectam via socket Unix.
2. Coletor — Injetado como IIFE na página. Percorre o DOM, lê estilos computados, valores declarados e métricas de elementos.
3. Analisador — Funções puras em Node.js. Classifica descobertas com níveis de confiança (DEFINITE / INDEFINITE / UNVERIFIABLE).
4. Renderizador — Gera saída em Markdown (padrão) ou JSON. Inclui diagrama de layout ASCII, árvore DOM e descobertas.

---

Início Rápido

1. Inspecionar uma 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 por Login

# 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. Saída em JSON

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

4. Usar como Servidor MCP (clientes de IA)

cssprobe-cli inclui um servidor MCP (stdio), então clientes de IA o chamam como ferramenta nativa — sem necessidade 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

Configuração manual para qualquer cliente MCP:

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

Expõe 10 ferramentas: cssprobe_open, cssprobe_inspect, cssprobe_tree, cssprobe_layout, cssprobe_findings, cssprobe_eval, cssprobe_screenshot, cssprobe_inject_css, cssprobe_close, cssprobe_status. Remova com cssprobe-cli mcp-uninstall.

---

Comandos

Gerenciamento de Sessão

Comando	Descrição
open [url]	Abrir navegador em modo de sessão (não bloqueante)
open [url] --headed	Mostrar janela do navegador
open [url] --state <file>	Abrir com cookies + localStorage salvos
open [url] --viewport 1280x720	Tamanho de viewport personalizado
close	Fechar sessão do navegador
close --all	Fechar todas as sessões em todos os espaços de trabalho
status	Mostrar status da sessão

Inspeção de CSS

Comando	Descrição
inspect <selector>	Diagnóstico completo de CSS (valores computados, valores declarados, descobertas)
inspect <selector> --layout	Incluir diagrama de layout ASCII
inspect <selector> --brief	Compacto: esboço da árvore + apenas avisos/erros
inspect <selector> --json	Saída estruturada em JSON
tree <selector>	Estrutura da árvore DOM
layout <selector>	Diagrama de layout ASCII
findings <selector>	Apenas problemas/avisos/erros

Injeção de CSS

Comando	Descrição
inject-css <css>	Injetar CSS na página atual

Navegador

Comando	Descrição
resize <width> <height>	Redimensionar viewport do navegador
eval <expression>	Avaliar JavaScript (contexto do navegador)
playwright <call>	Executar API do Playwright (contexto Node.js)
screenshot	Tirar captura de tela (salva em ~/.cssprobe-cli/screenshots/, use --out para substituir)

Estado

Comando	Descrição
state-import <file>	Importar cookies do formato Netscape
state-save	Salvar estado atual da sessão do navegador (cookies + localStorage)

Configuração

Comando	Descrição
config-show	Mostrar configuração atual
config-set <key> <value>	Definir valor de configuração
config-list	Listar todos os perfis
config-use <name>	Alternar perfil ativo
config-new <name>	Criar novo perfil
config-path	Mostrar caminho do arquivo de configuração

---

Modelo de Confiança

Cada descoberta carrega um nível de confiança:

Nível	Significado
DEFINITE	Baseado em valores computados (fatos de getComputedStyle) ou valores declarados acessíveis
INDEFINITE	Valor declarado usa % — resolve em tempo de execução
UNVERIFIABLE	Valor declarado ausente ou de folha de estilo de origem cruzada bloqueada

O cabeçalho do relatório mostra: confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1

---

Ferramenta Complementar: cssgraph

cssprobe-cli é uma sonda CSS de tempo de execução — ele abre um navegador real e lê o que está realmente renderizado. Para perguntas estáticas sobre o código-fonte — onde .btn-primary está definido, o que cascateia sobre ele, quais componentes o referenciam, o que mudaria se eu o editasse — use cssgraph, um grafo de conhecimento SQLite local de cada className, propriedade, variável e at-rule em suas folhas de estilo. 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 computados + DOM)
Responde	onde uma classe é definida, cascata, impacto, CSS não utilizado	layout realmente renderizado, overflow, rolagem, cadeias de altura
Quando	antes/sem 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á primeiro ao estático, 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)
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

Instalação: npm install -g cssgraph (requer Node.js >= 22.5.0). Expõe 12 ferramentas MCP (cssgraph_explore, cssgraph_rule, cssgraph_impact, …) além de comandos CLI. Veja npm / GitHub.

---

Configuração

# 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

Prioridade: flags de CLI > variáveis de ambiente > arquivo de configuração

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

Arquivo de configuração: ~/.cssprobe-clirc

---

Plataformas Suportadas

Plataforma	Arquiteturas
macOS	x64, arm64
Linux	x64, arm64
Windows	x64, arm64

---

Desenvolvimento

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

Se cssprobe-cli for útil

Uma ⭐ estrela ajuda outros desenvolvedores a descobri-lo — e nos diz para continuar lançando novidades.

---

Licença

MIT