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.

Features

• 📱 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

Installation

# Using npm
npm install -g @twocircles/karen-cli

# Using pnpm
pnpm add -g @twocircles/karen-cli

# Using yarn
yarn global add @twocircles/karen-cli

Quick Start

1. Configure your API key (for AI analysis)

# Set your Anthropic API key
karen config set api-key sk-ant-api03-YOUR_KEY_HERE

# Verify it's saved
karen config get api-key

2. Run your first audit

# Basic audit (no AI)
karen audit https://example.com --no-ai

# AI-powered audit (uses saved API key)
karen audit https://example.com

Get your Anthropic API Key

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_HERE

Example Output

Karen generates detailed reports with actionable fixes:

Karen's Verdict:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Issues: 147
  🚨 Critical: 12
  ⚠️  High: 34
  📋 Medium: 67
  ℹ️  Low: 34

Issues 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

karen audit - Run a website audit

# Basic audit (no AI)
karen audit https://example.com --no-ai

# AI-powered audit (uses saved API key)
karen audit https://example.com

# Override API key for one-time use
karen audit https://example.com --api-key sk-ant-xxx

# Custom config file
karen audit https://example.com --config ./karen.config.js

# Custom output paths
karen audit https://example.com \
  --output ./results.json \
  --markdown ./REPORT.md

# Create GitHub PR with fixes automatically
karen audit https://example.com --create-pr

# Use custom branch name for PR
karen audit https://example.com \
  --create-pr \
  --branch my-custom-fixes

Available Options

• --api-key <key> - Override API key for this audit
• --no-ai - Disable AI visual analysis
• --config <path> - Path to custom config file
• --output <path> - JSON output path (default: ./karen-tasks.json)
• --markdown <path> - Markdown report path (default: ./KAREN_TASKS.md)
• --create-pr - Auto-create GitHub PR with fixes (requires gh CLI)
• --branch <name> - Custom branch name for PR
• --github-repo <url> - GitHub repository URL (auto-detects from git remote)

karen config - Manage CLI configuration

# Set your API key (saves to ~/.karen/config.json)
karen config set api-key sk-ant-api03-YOUR_KEY_HERE

# Get your API key (masked for security)
karen config get api-key

# Show config file location
karen config path

Environment Variables

You can also configure Karen using environment variables:

# Option 1: Set in your shell
export ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE
karen audit https://example.com

# Option 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

Auto-create PRs with fixes

Karen can automatically create GitHub pull requests with fix suggestions:

# Prerequisites: Install and authenticate with gh CLI
gh auth login

# Run audit and create PR
karen audit https://example.com --create-pr

# Use 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

CI/CD Integration

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:

- 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

Custom Config File

Create a karen.config.js file to customize audit behavior:

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',
};

Audit Features

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)

License

MIT © Sahar Barak