cssgraph
by mack-peng
README.md
<div align="center">
# cssgraph
### CSS Intelligence for AI Coding Agents
**Surgical style context · fewer tool calls · faster answers · 100% local**
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/cssgraph)
[](https://www.npmjs.com/package/cssgraph)
[](https://github.com/mack-peng/cssgraph/stargazers)
[](#supported-platforms)
[](#supported-platforms)
[](#supported-platforms)
</div>
---
## 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.):
```text
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](docs/guide/installation.md), but seriously, let an agent do it. Humans fat-finger configs.
### For LLM Agents
Fetch the installation guide and follow it:
```bash
curl -s https://raw.githubusercontent.com/mack-peng/cssgraph/main/docs/guide/installation.md
```
---
## Quick Start
### 1. Initialize
```bash
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
```bash
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:
```json
{
"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
```bash
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.
| 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_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 |
---
## 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](https://github.com/mack-peng/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:
```bash
# 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](https://www.npmjs.com/package/cssprobe-cli) / [GitHub](https://github.com/mack-peng/cssprobe-cli).
---
## 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:
```json
{
"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 |
---
## If cssgraph is useful
A ⭐ star helps other developers discover it — and tells us to keep shipping.
---
## License
MIT
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo issues