cssprobe-cli
Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts and more in a live browser. Built for both humans and AI agents.
Static + runtime CSS diagnosis for AI agents — pair with cssgraph (the CSS knowledge graph) for the full picture.
Why cssprobe-cli?
When an AI agent needs to debug CSS — why is this element overflowing, what's the actual rendered layout, is this container scrollable — it can't see the browser. It guesses from static code, missing runtime-only issues like overflow, scroll chains, and containing block hijacks.
cssprobe-cli gives the agent eyes. It opens a real browser, collects computed styles and metrics via injected JavaScript, analyzes them with a confidence model, and returns structured findings — all in one command. The agent asks a question about any selector and gets back the DOM tree, ASCII layout diagram, overflow warnings, and scroll diagnosis without leaving the terminal.
Installation
For Humans
Copy and paste this prompt to your LLM agent (Claude Code, Cursor, Codex, etc.):
Install and configure cssprobe-cli by following the instructions here:
https://raw.githubusercontent.com/mack-peng/cssprobe-cli/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/cssprobe-cli/main/docs/guide/installation.md
Or install directly:
npm install -g cssprobe-cli
cssprobe-cli skill-install
How It Works
┌───────────────────────────────────────────────────────────┐
│ AI Agent │
│ │
│ "Is .sidebar overflowing?" │
│ calls: cssprobe-cli inspect .sidebar │
│ │ │
└─────────────────────────────┬─────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ cssprobe-cli daemon │
│ │
│ collector (IIFE) → analyzer (pure) → renderer (md/json) │
│ │ │
│ ▼ │
│ Playwright browser (Chromium) │
│ getBoundingClientRect · getComputedStyle · DOM walk │
└───────────────────────────────────────────────────────────┘
- Session —
open spawns a daemon process managing a browser. Commands connect via Unix socket.
- Collector — Injected as IIFE into the page. Walks the DOM, reads computed styles, declared values, and element metrics.
- Analyzer — Pure Node.js functions. Classifies findings with confidence levels (DEFINITE / INDEFINITE / UNVERIFIABLE).
- Renderer — Outputs Markdown (default) or JSON. Includes ASCII layout diagram, DOM tree, and findings.
Quick Start
1. Inspect a Page
cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout
cssprobe-cli inspect .container
cssprobe-cli layout .container
cssprobe-cli findings .container
cssprobe-cli close
2. Login-Protected Pages
cssprobe-cli open https://mysite.com --headed
cssprobe-cli state-save --name mysite
cssprobe-cli open https://mysite.com --state state.json --headed
3. JSON Output
cssprobe-cli inspect body --json
cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
4. Use as an MCP Server (AI clients)
cssprobe-cli ships an MCP server (stdio), so AI clients call it as a native tool — no shell needed:
cssprobe-cli mcp-install
cssprobe-cli mcp-install --target=claude,cursor,codex
cssprobe-cli mcp-install --local
Manual configuration for any MCP client:
{
"mcpServers": {
"cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
}
}
Exposes 10 tools: cssprobe_open, cssprobe_inspect, cssprobe_tree, cssprobe_layout,
cssprobe_findings, cssprobe_eval, cssprobe_screenshot, cssprobe_inject_css,
cssprobe_close, cssprobe_status. Remove with cssprobe-cli mcp-uninstall.
Commands
Session Management
| Command | Description |
|---|
open [url] | Open browser in session mode (non-blocking) |
open [url] --headed | Show browser window |
open [url] --state <file> | Open with saved cookies + localStorage |
open [url] --viewport 1280x720 | Custom viewport size |
close | Close browser session |
close --all | Close all sessions across all workspaces |
status | Show session status |
CSS Inspection
| Command | Description |
|---|
inspect <selector> | Full CSS diagnosis (computed values, declared values, findings) |
inspect <selector> --layout | Include ASCII layout diagram |
inspect <selector> --brief | Compact: tree sketch + warnings/errors only |
inspect <selector> --json | Structured JSON output |
tree <selector> | DOM tree structure |
layout <selector> | ASCII layout diagram |
findings <selector> | Only issues/warnings/errors |
CSS Injection
| Command | Description |
|---|
inject-css <css> | Inject CSS into current page |
Browser
| Command | Description |
|---|
resize <width> <height> | Resize browser viewport |
eval <expression> | Evaluate JavaScript (browser context) |
playwright <call> | Execute Playwright API (Node.js context) |
screenshot | Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override) |
State
| Command | Description |
|---|
state-import <file> | Import cookies from Netscape format |
state-save | Save current browser session state (cookies + localStorage) |
Configuration
| Command | Description |
|---|
config-show | Show current config |
config-set <key> <value> | Set config value |
config-list | List all profiles |
config-use <name> | Switch active profile |
config-new <name> | Create new profile |
config-path | Show config file path |
Confidence Model
Every finding carries a confidence level:
| Level | Meaning |
|---|
| DEFINITE | Based on computed values (facts from getComputedStyle) or accessible declared values |
| INDEFINITE | Declared value uses % — resolves at runtime |
| UNVERIFIABLE | Declared value missing or from blocked cross-origin stylesheet |
The report header shows: confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
cssprobe-cli is a runtime CSS probe — it opens a real browser and reads what is actually rendered. For static questions about the source code — where is .btn-primary defined, what cascades over it, which components reference it, what would change if I edited it — use cssgraph, a local SQLite knowledge graph of every className, property, variable, and at-rule in your stylesheets. 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:
cssgraph explore .btn-primary
cssgraph cascade .btn-primary
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary
Install: npm install -g cssgraph (requires Node.js >= 22.5.0). It exposes 12 MCP tools (cssgraph_explore, cssgraph_rule, cssgraph_impact, …) plus CLI commands. See npm / GitHub.
Configuration
cssprobe-cli config-set browser chromium
cssprobe-cli config-set depth 8
cssprobe-cli config-set viewport 375x812
cssprobe-cli config-new staging
cssprobe-cli -p staging config-set browser firefox
cssprobe-cli config-use staging
Priority: CLI flags > Environment variables > Config file
--browser CSSPROBE_BROWSER
--depth CSSPROBE_DEPTH
--headed CSSPROBE_HEADED
--viewport CSSPROBE_VIEWPORT
-p, --profile CSSPROBE_PROFILE
Config file: ~/.cssprobe-clirc
| Platform | Architectures |
|---|
| macOS | x64, arm64 |
| Linux | x64, arm64 |
| Windows | x64, arm64 |
Development
npm install
npm run build
npm test
npx tsc --noEmit
If cssprobe-cli is useful
A ⭐ star helps other developers discover it — and tells us to keep shipping.
License
MIT