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

``bash


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

$3

`bash


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
`

$3

`bash


Basic audit (no AI)

karen audit https://example.com --no-ai

AI-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_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

$3

`bash


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 - 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_HERE

Get your API key (masked for security)

karen config get api-key

Show 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.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

$3

Karen can automatically create GitHub pull requests with fix suggestions:

`bash


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

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

$3

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