A modern code complexity analyzer that helps developers write maintainable code through actionable insights. Unlike traditional tools, it measures both cyclomatic and cognitive complexity, showing you not just that code is complex, but why and how to fix it.
We've all seen this function:
function processUserData(user, settings, permissions) {
if (user.active) {
if (user.verified) {
if (settings.advanced) {
if (permissions.includes('admin')) {
// ... 50 more lines of nested logic
}
}
}
}
}This tool doesn't just say "complexity: 15" - it explains why it's hard to understand and how to refactor it.
- 🎯 Dual Complexity Metrics
- Cyclomatic: Counts code paths (traditional)
- Cognitive: Measures human understanding difficulty (innovative)
- 🚦 Actionable Feedback - Explains why functions are complex
- 🔒 Git Hooks - Prevent complex code from being committed
- 🤖 CI/CD Integration - Automated PR checks with GitHub Actions
- 🧑💻 Claude Code Support - Works as a Claude Code hook
- ⚡ Fast - Built with Bun and TypeScript
- 🎨 Beautiful Output - Color-coded terminal output with helpful indicators
Install directly from GitHub:
npm install -D git+https://github.com/hew/claude-code-complexity-analyzer.git
# or
yarn add -D git+https://github.com/hew/claude-code-complexity-analyzer.git
# or
bun add -D git+https://github.com/hew/claude-code-complexity-analyzer.git
# Or clone and link locally:
git clone https://github.com/hew/claude-code-complexity-analyzer.git
cd claude-code-complexity-analyzer
bun install
bun run build
npm link# Analyze your source code
npx complexity-analyzer analyze src
# Set up git hooks (recommended)
npx complexity-analyzer setup-hooks
# Check specific files
npx complexity-analyzer analyze src/components --max-complexity 15When you try to commit complex code:
git commit -m "feat: add user processing"
🔍 Running complexity analysis on staged files...
⚠️ High complexity in src/UserService.ts:
processUser:45 | Cyclo: 12 | Cogn: 24
↳ High nesting or logical complexity
❌ Commit blocked: High complexity detected
Options:
1. Refactor the complex functions
2. Override with: git commit --no-verify
3. Increase limit: MAX_COMPLEXITY=15 git commitThe tool shows both metrics side-by-side:
getUserData:23 | Cyclo: 14 | Cogn: 6
↳ Linear control flow (e.g., else-if chains)
processPayment:89 | Cyclo: 8 | Cogn: 22
↳ High nesting or logical complexity
This tells you:
getUserDatahas many branches but they're linear (less problematic)processPaymenthas deeply nested logic (needs refactoring)
On every pull request:
## ✅ Complexity Analysis Results
High Complexity Functions:
- fetchUserData:34 | Cyclo: 11 | Cogn: 18
Summary:
Total functions analyzed: 47
Functions exceeding threshold: 1
💡 Tip: Functions with high cognitive complexity are harder to understand than those with high cyclomatic complexity.Claude sees complexity warnings before editing:
🔍 Analyzing complexity for src/api.ts...
⚠️ Complex functions detected:
handleRequest:67 | Cyclo: 9 | Cogn: 15
💡 Consider refactoring before adding new features.
Traditional metric that counts decision points:
- Each
if,for,while,caseadds +1 - Linear and predictable
- Good for measuring test coverage needs
Modern metric that measures human understanding:
- Penalizes nesting (deeper = harder)
- Ignores linear else-if chains
- Considers logical operator sequences
- Better represents actual maintainability
// HIGH Cyclomatic (7), LOW Cognitive (1)
function getStatus(code: number) {
if (code === 200) return 'success';
else if (code === 201) return 'created';
else if (code === 400) return 'bad request';
else if (code === 401) return 'unauthorized';
else if (code === 404) return 'not found';
else if (code === 500) return 'server error';
else return 'unknown';
}
// LOW Cyclomatic (4), HIGH Cognitive (9)
function processRequest(user: User, request: Request) {
if (user.authenticated) { // +1
if (request.method === 'POST') { // +2 (nested)
if (user.permissions.includes('write')) { // +3 (deeper)
if (request.body.valid) { // +4 (even deeper)
// process...
}
}
}
}
}# Automatic setup
npx complexity-analyzer setup-hooks
# Manual setup
ln -sf node_modules/@hew/complexity-analyzer/hooks/pre-commit .git/hooks/pre-commitIn package.json:
{
"complexity-analyzer": {
"maxCyclomatic": 10,
"maxCognitive": 15,
"exclude": ["**/*.test.ts", "**/*.spec.ts"],
"failOn": "error"
}
}Or via environment variables:
MAX_COMPLEXITY=15 git commit
COMPLEXITY_EXCLUDE="test/**" npx complexity-analyzer analyzeAdd to .github/workflows/complexity.yml:
name: Complexity Check
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v1
- run: bun install
- run: npx complexity-analyzer analyze src --max-complexity 10import {
calculateCyclomaticComplexity,
calculateCognitiveComplexity
} from 'claude-code-complexity-analyzer';
const code = `
function example(x: number) {
if (x > 0) return 'positive';
return 'negative';
}
`;
const cyclomatic = calculateCyclomaticComplexity(code); // 2
const cognitive = calculateCognitiveComplexity(code); // 1| Complexity | Cyclomatic | Cognitive | Action |
|---|---|---|---|
| ✅ Simple | 1-5 | 0-5 | Good! |
| 🟡 Moderate | 6-10 | 6-10 | Consider refactoring |
| 🟠 Complex | 11-20 | 11-20 | Should refactor |
| 🔴 Very Complex | 21+ | 21+ | Must refactor |
# Clone the repo
git clone https://github.com/hew/claude-code-complexity-analyzer
cd claude-code-complexity-analyzer
# Install dependencies
bun install
# Run tests
bun test
# Analyze the analyzer itself!
bun run analyze:self
# Set up git hooks
bun run setup-hooksWe welcome contributions! Please ensure:
- All tests pass (
bun test) - Complexity thresholds are met (
bun run analyze) - Code follows existing patterns
MIT
- VSCode extension with inline hints
- Historical tracking with git integration
- HTML reports with charts
- More metrics (Halstead, Maintainability Index)
- Language support beyond JS/TS