io.github.mack-peng/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 <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 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

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.*, **/*.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