Karen CLI - Sassy CSS Layout Auditor
npm install @twocircles/karen-cli> Sassy CSS layout auditor with AI-powered visual analysis
Karen CLI is a command-line CSS layout auditing tool that examines websites across multiple viewports, uses AI to detect visual and code-level issues, and generates actionable fix recommendations.
- š± Multi-viewport Testing: Test across 100+ device viewports (mobile, tablet, desktop, ultrawide)
- š¤ AI-Powered Analysis: Claude vision API for detecting visual layout issues
- āæ Accessibility Checks: WCAG contrast ratio validation
- š Design System Enforcement: Spacing scale, typescale, and color palette validation
- ā” Performance Audits: Core Web Vitals (LCP, CLS, INP, TTFB, FCP)
- š§ Auto-fix Suggestions: Get code fixes for detected issues
- š GitHub Integration: Auto-create PRs with fixes using --create-pr
- š Multiple Output Formats: JSON and Markdown reports
``bashUsing npm
npm install -g @twocircles/karen-cli
Quick Start
$3
`bash
Set your Anthropic API key
karen config set api-key sk-ant-api03-YOUR_KEY_HEREVerify it's saved
karen config get api-key
`$3
`bash
Basic audit (no AI)
karen audit https://example.com --no-aiAI-powered audit (uses saved API key)
karen audit https://example.com
`$3
1. Sign up at console.anthropic.com
2. Navigate to API Keys in your account settings
3. Create a new API key
4. Save it with:
karen config set api-key sk-ant-api03-YOUR_KEY_HEREExample Output
Karen generates detailed reports with actionable fixes:
`
Karen's Verdict:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Total Issues: 147
šØ Critical: 12
ā ļø High: 34
š Medium: 67
ā¹ļø Low: 34Issues by Type:
performance: 28
overflow: 15
spacing: 42
accessibility: 31
typescale: 18
colors: 13
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
š Full report: ./karen-tasks.json
š Markdown report: ./KAREN_TASKS.md
`Each issue includes:
- Severity level (critical, high, medium, low)
- Element selector for easy debugging
- Viewport information (which device breakpoint)
- Fix suggestion with before/after code snippets
- AI visual analysis (when enabled)
CLI Commands
$3
`bash
Basic audit (no AI)
karen audit https://example.com --no-aiAI-powered audit (uses saved API key)
karen audit https://example.comOverride API key for one-time use
karen audit https://example.com --api-key sk-ant-xxxCustom config file
karen audit https://example.com --config ./karen.config.jsCustom output paths
karen audit https://example.com \
--output ./results.json \
--markdown ./REPORT.mdCreate GitHub PR with fixes automatically
karen audit https://example.com --create-prUse custom branch name for PR
karen audit https://example.com \
--create-pr \
--branch my-custom-fixes
`#### Available Options
-
--api-key - Override API key for this audit
- --no-ai - Disable AI visual analysis
- --config - Path to custom config file
- --output - JSON output path (default: ./karen-tasks.json)
- --markdown - Markdown report path (default: ./KAREN_TASKS.md)
- --create-pr - Auto-create GitHub PR with fixes (requires gh CLI)
- --branch - Custom branch name for PR
- --github-repo - GitHub repository URL (auto-detects from git remote)$3
`bash
Set your API key (saves to ~/.karen/config.json)
karen config set api-key sk-ant-api03-YOUR_KEY_HEREGet your API key (masked for security)
karen config get api-keyShow config file location
karen config path
`$3
You can also configure Karen using environment variables:
`bash
Option 1: Set in your shell
export ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE
karen audit https://example.comOption 2: Inline
ANTHROPIC_API_KEY=sk-ant-xxx karen audit https://example.com
`Priority order (highest to lowest):
1. CLI flag (
--api-key)
2. Environment variable (ANTHROPIC_API_KEY)
3. Config file (~/.karen/config.json)GitHub Integration
$3
Karen can automatically create GitHub pull requests with fix suggestions:
`bash
Prerequisites: Install and authenticate with gh CLI
gh auth loginRun audit and create PR
karen audit https://example.com --create-prUse custom branch name
karen audit https://example.com --create-pr --branch karen-layout-fixes
`The PR will include:
- Markdown report with all issues
- JSON data file for programmatic processing
- Fix suggestions for each issue
$3
You can run Karen in your CI/CD pipeline to catch layout issues before they reach production. See the GitHub Actions workflow example for automated PR comments.
Example GitHub Action:
`yaml
- name: Run Karen Audit
run: |
npm install -g @twocircles/karen-cli
karen audit ${{ env.DEPLOY_URL }} --no-ai --output audit.json
continue-on-error: true
`Configuration
$3
Create a
karen.config.js file to customize audit behavior:`javascript
export default {
// Define your spacing scale (in px)
spacingScale: [0, 4, 8, 12, 16, 24, 32, 48, 64], // Typography scale configuration
typescale: {
base: 16,
ratio: 1.25,
sizes: [12, 14, 16, 20, 25, 31, 39, 49],
},
// Brand color palette for validation
colorPalette: [
'#F5E6D3',
'#D4A574',
'#8B7355',
],
// Custom breakpoints (or use default 100+ devices)
breakpoints: [
{ name: 'mobile', width: 375, height: 667 },
{ name: 'tablet', width: 768, height: 1024 },
{ name: 'desktop', width: 1440, height: 900 },
],
// Exit with error code if issues found
failOn: ['critical', 'high'],
// Enable/disable audit features
features: [
'overflow', // Detect horizontal scrolling
'spacing', // Validate spacing consistency
'typescale', // Check typography scale
'colors', // Validate color palette
'accessibility', // WCAG contrast ratios
'design-system', // Design token consistency
'performance', // Core Web Vitals
],
// Optional: Anthropic API key (better to use config command)
// anthropicApiKey: 'sk-ant-xxx',
};
``Karen detects the following types of issues:
- Overflow - Horizontal scrolling bugs
- Spacing - Inconsistent margins/padding
- Typescale - Font sizes not following scale
- Colors - Colors not in defined palette
- Accessibility - WCAG contrast ratio violations
- Design System - Misaligned elements, inconsistent patterns
- Performance - Core Web Vitals issues (LCP, CLS, INP, TTFB, FCP)
MIT Ā© Sahar Barak