The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Stylespeak listing page.
A companion MCP server and CLI to stylesafe that makes CSS legible to AI agents — resolving cascade, tracing properties, predicting change impact, and explaining what applies and why before an agent touches a single line of styles.
AI coding agents write CSS without being able to see its effect. They modify a rule, assume it worked, and move on — unaware that a higher-specificity rule elsewhere already overrides it, a combinator rule in another file is silently winning, or a CSS variable resolves to something entirely different than expected. stylespeak gives agents a structured knowledge layer to consult before making changes.
resolve_styles — answers "what CSS actually applies to this selector?"
Given a selector and a set of files, returns every CSS property the selector would receive, which rule wins for each, and which rules were overridden — with confidence levels since no real DOM is available. CSS custom properties (var()) are resolved to their actual values, including chained variables, fallbacks, and media-context overrides.
trace_property — answers "everywhere this property is set, who wins?"
Given a property name and a set of files, returns every rule that sets it, groups competing rules that target overlapping selectors, and shows the full cascade chain for each group — with resolved variable values included.
impact_preview — answers "if I change this, what else breaks?"
Given a selector, property, and optional new value, predicts the full blast radius of the change before it's made — showing which selectors will see a different value, which are shielded by higher specificity, which cascade relationships are uncertain, and which downstream rules are affected through CSS variable chains or property inheritance. Works without a browser.
style_manifest — answers "what does this entire project's CSS look like at a glance?"
Builds a compressed, structured summary of a project's entire CSS knowledge — selectors, properties, variables, competition groups, and risk hotspots — that an agent can load once at the start of a session and keep in context instead of repeatedly querying individual files.
live_resolve — answers "what does the browser actually compute for this selector?"
Queries a running Chromium browser via CDP and returns exact computed styles and matched rules. No heuristics, no confidence levels — the browser resolved it. Requires Chrome running with --remote-debugging-port=9222.
Add to your MCP client config (Cursor: .cursor/mcp.json, VS Code: .vscode/mcp.json):
Once connected, agents can call:
resolve_styles({ selector, files, projectRoot, componentFiles? })trace_property({ property, files, projectRoot })impact_preview({ selector, property, newValue?, files, projectRoot })style_manifest({ files?, projectRoot?, maxSelectors? })live_resolve({ selector, port?, tabUrl? })| Level | Meaning |
|---|---|
certain | Exact selector match — rule definitively applies |
likely | Rule tokens are a subset of the queried selector — applies in most cases |
possible | Combinator rule — depends on DOM ancestry, unknown without rendering |
exact | Returned by live_resolve only — browser-resolved, no heuristics |
As of v0.2, stylespeak fully resolves CSS custom properties (var()) in all output:
value — the raw value as written (var(--color-primary))resolvedValue — the actual resolved value (#2563eb)variableChain — the full resolution path, including chained variablesconditionalValues — media-context overrides where the variable resolves differentlySupported: simple, fallback, nested fallback, chained, scoped, media-context, circular reference protection.
stylesafe catches problems in your CSS — conflicts, dead rules, Tailwind clashes — before they ship.
stylespeak explains your CSS — resolving cascade, tracing properties, predicting impact, resolving variables — so agents understand before they act.
Use stylesafe as a post-edit check. Use stylespeak as a pre-edit consultation. Together they give AI coding agents a complete feedback loop on styles.
live_resolve requires a Chromium browser running with remote debugging enabled:
Security note: Never run
--remote-debugging-porton a machine exposed to untrusted networks or in production. This flag opens a local API that any process on the machine can connect to.
| Format | Support level |
|---|---|
.css | Full |
.scss | Full — nesting, & references, @media passthrough |
.module.css / .module.scss | Full — locally scoped classes detected and tagged |
| vanilla-extract / Linaria / StyleX | Supported via compiled CSS output |
| styled-components / Emotion | Not supported — dynamic runtime styles |
| CSS-in-JS object syntax | Not supported (post v1.0 roadmap) |
Zero external dependencies. Requires Node.js 21+.