The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cssgraph listing page.
Surgical style context · fewer tool calls · faster answers · 100% local
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.
Copy and paste this prompt to your LLM agent (Claude Code, Cursor, Codex, etc.):
Or read the Installation Guide, but seriously, let an agent do it. Humans fat-finger configs.
Fetch the installation guide and follow it:
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).
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:
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.
styled.div), JSX className references, and template class attributes extracted from .jsx/.tsx/.erb/.haml files..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.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).git ls-files for instant file discovery. Falls back to filesystem walk on non-git projects.Promise.all. Parses complete concurrently; results flushed in file order for correctness.cssgraph always scans:
className references, CSS-in-JS, CSS Modules.erb, .haml, .html files for class="..." attributes and Haml .classname shorthandThis 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 |
| 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_diagnose | Static anchor diagnosis for scroll/height issues — classifies height declarations as DEFINITE / INDEFINITE / UNVERIFIABLE along the ancestor chain |
cssgraph_property | Search selectors by CSS property value |
cssgraph_files | Indexed style file tree |
cssgraph_status | Index health check |
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:
| cssgraph (static) | cssprobe-cli (runtime) | |
|---|---|---|
| Analyzes | source code (CSS/SCSS/Less + JSX/TSX + templates) | live browser (computed styles + DOM) |
| Answers | where a class is defined, cascade, impact, unused CSS | actual rendered layout, overflow, scroll, height chains |
| When | before/without a browser | after static analysis, to verify at runtime |
| Usage | cssgraph init + explore/rule/impact | open + inspect/layout/findings |
Recommended workflow for a style problem — go static first, then verify at runtime:
Install: npm install -g cssprobe-cli (requires Node.js >= 22.5.0). See npm / GitHub.
| 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 |
| Project | Total files | First index | Nodes | Edges |
|---|---|---|---|---|
| Small | ~50 | ~15s | ~16K | ~50K |
| Production monorepo | ~11K | ~3-5m | ~780K | ~22M |
Zero-config by default. Optional .cssgraph.json at your project root:
Built-in default excludes (always applied): **/*.test.*, **/*.stories.*, **/*.spec.*, **/*.min.*, **/__tests__/**, **/__snapshots__/**, **/__mocks__/**, **/generated/**, **/spec/**, **/vendor/**.
| Platform | Architectures | Install |
|---|---|---|
| macOS | x64, arm64 | npm |
| Linux | x64, arm64 | npm |
| Windows | x64, arm64 | npm |
A ⭐ star helps other developers discover it — and tells us to keep shipping.
MIT