Cssgraph

cssgraph

CSS Intelligence for AI Coding Agents

Surgical style context · fewer tool calls · faster answers · 100% local

---

Why cssgraph?

When an AI agent needs to understand CSS — where is .btn-primary defined, what properties does it have, which selectors cascade over it, which JSX components reference it — it discovers style the slow way: grep, glob, and Read, one file at a time, reconstructing the cascade by hand.

cssgraph hands the agent the exact style context it needs in one call. It's a pre-built knowledge graph of every className, CSS property, variable, and at-rule in your stylesheets — so instead of crawling files, the agent asks one question and gets back the properties, overrides, specificity, callers, and file-level impact in full.

---

Installation

For Humans

Copy and paste this prompt to your LLM agent (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

Or read the Installation Guide, but seriously, let an agent do it. Humans fat-finger configs.

For LLM Agents

Fetch the installation guide and follow it:

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

---

Quick Start

1. Initialize

npm i -g cssgraph

cd your-project cssgraph init --workers 8

Indexes all style files (CSS, SCSS, Less, Sass), JSX/TSX className references, CSS-in-JS, CSS Modules, and view templates (ERB/Haml/HTML) — enabling every MCP tool.

Pass --workers to control parallel parse threads (default: cpu cores - 1).

Requires Node.js >= 22.5.0 (for node:sqlite).

2. Wire up your agent

cssgraph mcp-install

Auto-detects and configures opencode, Claude Code, Cursor, Codex CLI, Gemini CLI, Hermes Agent, Antigravity IDE, and Kiro. Writes MCP server config, instructions block, and an Agent Skill (SKILL.md + references/pitfalls.md) that teaches agents when to use each of the 13 cssgraph tools, how to chain them into workflows, and what pitfalls to avoid.

Or add to any MCP agent manually:

{

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

3. No more syncing

Auto-sync is enabled by default. The MCP server watches your project and updates the graph on every file change — while your agent edits code, or you add/modify/delete CSS files. The index is never stale.

---

How It Works

┌───────────────────────────────────────────────────────────┐

│ 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. Extraction — PostCSS parses CSS/SCSS/Less/Sass into ASTs. CSS-in-JS (styled.div), JSX className references, and template class attributes extracted from .jsx/.tsx/.erb/.haml files.
2. Storage — Everything goes into a local SQLite database (.cssgraph/cssgraph.db) with FTS5 full-text search. WAL-mode + batch commits for write performance. FTS triggers and unique indexes are deferred during bulk load for speed.
3. Graph — Edges connect related nodes: contains (selector→property), nests (parent→child selector), overrides (higher specificity selector overrides lower), imports (file→imported file), references (JSX/view file→className, property→CSS variable).
4. Git-first scanning — git ls-files for instant file discovery. Falls back to filesystem walk on non-git projects.
5. Parallel parsing — Files dispatched in batches to worker threads via Promise.all. Parses complete concurrently; results flushed in file order for correctness.
6. Auto-Sync — Native OS file events, debounced, incrementally synced.

---

CLI Reference

cssgraph init [path] [-w, --workers <n>]  # Initialize + build graph

cssgraph index [path] [-w, --workers ] # Rebuild from scratch cssgraph query # Search for className selectors cssgraph explore # Full style context for a className cssgraph details # O(1) exact selector → file:line lookup cssgraph rule [--strict] # Selector impact: exact + loose/strict files cssgraph impact-selector # Code files affected by a selector cssgraph impact # Blast radius of changing a className cssgraph unused # Find unreferenced class selectors cssgraph cascade # Visualize cascade path cssgraph diagnose [chain...] # Static anchor diagnosis (height/scroll) cssgraph property # 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

JSX and View File Scanning (default)

cssgraph always scans:

• JSX/TSX/JS/TS/ES6 — className references, CSS-in-JS, CSS Modules
• View templates — .erb, .haml, .html files for class="..." attributes and Haml .classname shorthand

This enables cssgraph_impact, cssgraph_callers, and cssgraph_rule to track both component files AND template files that reference each className.

---

MCP Tools

---

Complementary Tool: cssprobe-cli

cssgraph is a static analysis tool — it reads your source code and answers where a class is defined, what cascades over it, and what a change would affect. For runtime questions — what a page actually renders in a browser (overflow, scroll chains, computed height chains, containing block hijacks) — use cssprobe-cli, which opens a real browser and reads computed styles plus DOM metrics. The two tools complement each other:

Recommended workflow for a style problem — go static first, then verify at runtime:

# 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

Install: npm install -g cssprobe-cli (requires Node.js >= 22.5.0). See npm / GitHub.

---

Supported Languages

---

Production Scale

---

Project Configuration

Zero-config by default. Optional .cssgraph.json at your project root:

{

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

Built-in default excludes (always applied): **/*.test.*,