butter-code-health

A global Node.js CLI tool that analyzes code health in TypeScript/JavaScript projects and provides a beautiful browser-based dashboard for visualizing static analysis results.

Features

• 🔍 Multi-tool Analysis: Combines ESLint, dependency-cruiser, knip, and cloc
• 📊 Browser Dashboard: Beautiful, interactive web UI for exploring results
• 👁️ Watch Mode: Live updates as you code
• 🏗️ Monorepo Support: Works with npm/yarn/pnpm workspaces
• 🚫 Zero Config: No files added to your repo by default
• 🎯 Smart Defaults: Sensible rules and thresholds out of the box

Installation

Install globally:

npm install -g butter-code-health

Or run directly with npx:

npx butter-code-health dashboard

Usage

Dashboard Mode (Recommended)

Launch an interactive dashboard to explore your code health:

# Basic dashboard
code-health dashboard

# With file watching and auto-refresh
code-health dashboard --watch

# Auto-open browser
code-health dashboard --open

Analyze Mode

Run a one-time analysis and view results:

code-health analyze

# With custom directory
code-health analyze --cwd /path/to/project

Print Mode (CI-Friendly)

Output analysis results to stdout:

# Text format (default)
code-health print

# JSON format for CI/CD pipelines
code-health print --format json

# Fails with exit code 1 if thresholds exceeded
code-health print --max-lines 300 --complexity-threshold 10

CLI Options

Global Options

• --cwd <path> - Set root directory for analysis (default: current directory)
• --include <glob,glob> - Include specific file patterns
• --exclude <glob,glob> - Exclude specific file patterns
• --no-gitignore - Don't use .gitignore for exclusions
• --port <number> - Dashboard server port (default: 43110)
• --open - Auto-open browser when server starts

Threshold Options

• --max-lines <n> - Max lines per file (default: 400)
• --max-lines-per-function <n> - Max lines per function (default: 80)
• --complexity-threshold <n> - Cognitive complexity threshold (default: 15)

MCP (Model Context Protocol) Integration

The tool includes an MCP server for AI assistant integration. Add to your .mcp.json:

{
  "mcpServers": {
    "code-health": {
      "command": "npx",
      "args": ["butter-code-health@latest", "code-health-mcp"],
      "env": {
        "CODE_HEALTH_AUTO_START": "true",
        "CODE_HEALTH_PORT": "3020"
      }
    }
  }
}

This allows AI assistants to analyze your code health directly.

What It Analyzes

📏 Code Size

• Lines of code per file
• Identifies largest files
• Tracks code vs comments vs blank lines

🧠 Cognitive Complexity

• Functions with high cognitive complexity
• Based on SonarJS rules
• Helps identify hard-to-maintain code

🔄 Dependency Cycles

• Circular dependencies between modules
• Helps maintain clean architecture
• Essential for large codebases

💀 Dead Code

• Unused files and exports
• Powered by knip
• Reduce bundle size and maintenance burden

📐 Code Standards

• Max lines violations
• TypeScript best practices
• Performance anti-patterns

Dashboard Features

The browser dashboard provides:

• Sortable Tables: Click headers to sort by any column
• Search & Filter: Quick filtering for all tables
• Live Updates: Auto-refresh in watch mode
• Copy to Clipboard: Easy sharing of findings
• Detailed Views: Expandable rows for more context

Default Ignore Patterns

The tool automatically ignores:

• node_modules/
• .git/
• Build outputs (dist/, build/, .next/)
• Cache directories
• Lock files
• Environment files
• Config files

Plus anything in your .gitignore (unless --no-gitignore is used).

Monorepo Support

Automatically detects and analyzes:

• npm/yarn workspaces (via package.json)
• pnpm workspaces (via pnpm-workspace.yaml)
• Common patterns (apps/*, packages/*)

Configuration

While the tool works with zero configuration, it respects existing project configs:

• ESLint configurations (flat or legacy)
• TypeScript configs for path resolution
• .gitignore for file exclusions

Examples

Analyze a TypeScript monorepo

cd /path/to/monorepo
npx butter-code-health dashboard --watch --open

CI/CD Integration

# In your CI pipeline
npx butter-code-health print --format json > code-health.json

# Or fail on violations
npx butter-code-health print --max-lines 500 --complexity-threshold 20

Custom Analysis

# Analyze specific directories
code-health analyze --include "src/**/*.ts" --exclude "**/*.test.ts"

# Override thresholds
code-health dashboard --max-lines 600 --max-lines-per-function 100

MCP Integration (Model Context Protocol)

This tool can be used as an MCP server, making it available to AI assistants like Claude Code for automatic code analysis.

Installation for MCP

Install globally:

npm install -g butter-code-health

Add to your .mcp.json file in your project root:

{
  "mcpServers": {
    "code-health": {
      "command": "code-health-mcp",
      "args": []
    }
  }
}

Or use with npx (if not installed globally):

{
  "mcpServers": {
    "code-health": {
      "command": "npx",
      "args": ["butter-code-health", "code-health-mcp"]
    }
  }
}

MCP Tools Available

Once configured, the following tools are available to AI assistants:

• code_health_analyze: Run comprehensive code health analysis
• code_health_dashboard: Start the dashboard server with browser UI
• code_health_stop_dashboard: Stop the running dashboard server
• code_health_summary: Get a quick summary of code health metrics

Example MCP Usage

AI assistants can now run commands like:

• "Analyze the code health of this project"
• "Start a code health dashboard for this codebase"
• "Show me a summary of code quality issues"

The dashboard will be automatically available at http://localhost:43110 when started via MCP.

Requirements

• Node.js 18 or higher
• Works with any JavaScript/TypeScript project

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.