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 <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 install

Auto-detects and configures opencode, Claude Code, Cursor, Codex CLI, Gemini CLI, Hermes Agent, Antigravity IDE, and Kiro.

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 <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 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 install                           # Auto-wire to your AI agent
cssgraph uninstall                         # Remove from your AI agent
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.

| Project | Total files | First index | Nodes | Edges | |---------|-------------|-------------|-------|-------| | Small | ~50 | ~15s | ~16K | ~50K | | Production monorepo | ~11K | ~3-5m | ~780K | ~22M |

MCP Tools

| Tool | Purpose | |------|---------| | cssgraph_explore | PRIMARY: Full style context for a className — properties, overrides, specificity, callers | | cssgraph_search | Search for className selectors by name | | cssgraph_callers | Find JSX components referencing a className | | cssgraph_impact | Blast radius of changing a className | | cssgraph_rule | Blast radius of a full CSS selector (exact match + loose/strict file impact) | | cssgraph_impact_selector | Find code files (JS/TS/JSX/TSX) affected by a CSS selector | | cssgraph_details | O(1) exact selector lookup (no edges, lightweight) | | cssgraph_unused | Find class selectors with no incoming references | | cssgraph_cascade | Visualize the cascade path for a className | | cssgraph_property | Search selectors by CSS property value | | cssgraph_files | Indexed style file tree | | cssgraph_status | Index health check |

Supported Languages

| Language | Extension | Extraction | |----------|-----------|------------| | CSS | .css | PostCSS standard | | SCSS | .scss | postcss-scss plugin | | Less | .less | postcss-less plugin | | Sass (indented) | .sass | Compile → PostCSS | | PostCSS custom | .pcss | PostCSS standard | | JSX / TSX | .jsx .tsx | className + CSS-in-JS | | JavaScript / TypeScript | .js .ts .es6 | className + CSS Modules | | ERB (Rails) | .erb | class="..." extraction | | Haml (Rails) | .haml | .classname + {:class =>} extraction | | HTML | .html | class="..." extraction | | CSS Modules | .module.css .module.scss .module.less | Dynamic import resolution | | Tailwind | tailwind.config.js + CSS @theme | v3 JS config + v4 CSS config |

Production Scale

| Project | Total files | First index | Nodes | Edges | |---------|-------------|-------------|-------|-------| | Small | ~50 | ~15s | ~16K | ~50K | | Production monorepo | ~11K | ~3-5m | ~780K | ~22M |

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

| Platform | Architectures | Install | |----------|---------------|---------| | macOS | x64, arm64 | npm | | Linux | x64, arm64 | npm | | Windows | x64, arm64 | npm |

License

MIT