Cssgraph

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 cssgraphcd your-projectcssgraph 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 <n> 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 graphcssgraph index [path] [-w, --workers <n>]  # Rebuild from scratchcssgraph query <className>                 # Search for className selectorscssgraph explore <query...>                # Full style context for a classNamecssgraph details <selector>                # O(1) exact selector → file:line lookupcssgraph rule <selector> [--strict]        # Selector impact: exact + loose/strict filescssgraph impact-selector <selector>       # Code files affected by a selectorcssgraph impact <className>                # Blast radius of changing a classNamecssgraph unused                            # Find unreferenced class selectorscssgraph cascade <className>               # Visualize cascade pathcssgraph diagnose <className> [chain...]   # Static anchor diagnosis (height/scroll)cssgraph property <query...>               # Search by CSS property valuecssgraph files [path]                      # Project style file treecssgraph status [path]                     # Index statisticscssgraph sync [path]                       # Incremental updatecssgraph serve --mcp                       # Start MCP servercssgraph 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-primarycssgraph cascade .btn-primary
# 2. Runtime: confirm what actually renders (cssprobe-cli)npm i -g cssprobe-clicssprobe-cli open https://example.comcssprobe-cli inspect .btn-primarycssprobe-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.*, **/*.stories.*, **/*.spec.*, **/*.min.*, **/__tests__/**, **/__snapshots__/**, **/__mocks__/**, **/generated/**, **/spec/**, **/vendor/**.

Supported Platforms

If cssgraph is useful

A ⭐ star helps other developers discover it — and tells us to keep shipping.

License

MIT