Claude Checkup 🔍

Audit your Claude Code setup and get actionable recommendations.

This tool provides high-level guidance on use of Claude Code, including published best practices from the likes of Boris Cherny (Creator of Claude Code). This package is not endorsed by Boris Cherny or Anthropic.

📖 Recommended Reading: Claude Code creator Boris shares his setup on Reddit

I plan on updating this package with the latest trends, optimizations, and Claude releases — but contributions are welcome! If you have insights to share, please open a PR.

Are you getting the most out of Claude Code? This CLI tool scans your project, compares it against best practices, and tells you exactly how to improve.

npx claude-checkup

What It Checks

Static Checks (always run)

| Category | What We Look For | |----------|------------------| | CLAUDE.md Health | Exists, reasonable size, recently updated, multiple contributors | | Workflow Automation | Slash commands configured, essential commands present | | Verification Loops | Test framework setup, verification instructions | | Hooks & Safety | PostToolUse formatting, safety hooks, permissions | | Git Integration | gh CLI or GitHub MCP configured |

Deep Analysis (with --deep flag)

| Category | What Claude Analyzes | |----------|---------------------| | CLAUDE.md Quality | Specificity, actionability, completeness - with AI-generated improvements | | Command Quality | Clarity and completeness of each slash command | | Hooks Safety | Security review of permissions and hook configuration |

Example Output

🔍 Claude Checkup v1.0.0

Scanning project...

Results:
┌─────────────────────┬────────┬───────┐
│ Category            │ Status │ Score │
├─────────────────────┼────────┼───────┤
│ CLAUDE.md Health    │ ⚠️      │ 2/4   │
│ Workflow Automation │ ❌      │ 0/3   │
│ Verification Loops  │ ✅      │ 2/2   │
│ Hooks & Safety      │ ❌      │ 0/2   │
│ Git Integration     │ ✅      │ 1/1   │
├─────────────────────┼────────┼───────┤
│ Overall             │ Interm │ 5/12  │
└─────────────────────┴────────┴───────┘

📄 Full report: .claude-checkup/report.md
🚀 Auto-apply:   npx claude-checkup --apply

The Report

The generated report includes:

• What's missing - Clear explanation of each gap
• Why it matters - Including quotes from Boris Cherny where relevant
• Exact fixes - Copy-paste ready code, not vague advice
• Extra options - Expandable sections with alternative approaches

Auto-Apply Fixes

Want Claude Code to implement the recommendations for you?

npx claude-checkup --apply

This generates a prompt file you can pass directly to Claude Code:

claude -p "$(cat .claude-checkup/apply-prompt.md)"

CLI Options

npx claude-checkup [options]

Options:
  -d, --deep             Run AI-powered deep analysis (requires claude CLI)
  -t, --timeout <secs>   Timeout per deep check (default: 60)
  -s, --stdout           Output report to stdout instead of file
  -a, --apply            Generate prompt for Claude Code to apply fixes
  -o, --output <dir>     Output directory (default: .claude-checkup)
  -j, --json             Output as JSON (for CI/tooling)
  -p, --path <path>      Path to project (default: current directory)
  -V, --version          Show version
  -h, --help             Show help

Deep Analysis Mode

Want Claude to review the quality of your setup, not just check if files exist?

npx claude-checkup --deep

This uses the Claude CLI to analyze:

• CLAUDE.md quality - Are your instructions specific and actionable, or vague boilerplate?
• Command quality - Are your slash commands clear and complete?
• Hooks safety - Any security concerns with your permissions?

The report includes AI-generated improved versions you can use directly.

Scoring

Standard Mode (12 points)

| Score | Tier | Description | |-------|------|-------------| | 0-3 | Beginner | Using Claude Code as a chat interface | | 4-7 | Intermediate | Building workflows, room to grow | | 8-10 | Advanced | Strong setup, minor optimizations available | | 11-12 | Expert | Boris-level setup 🎯 |

Deep Mode (18 points)

| Score | Tier | Description | |-------|------|-------------| | 0-5 | Beginner | Using Claude Code as a chat interface | | 6-10 | Intermediate | Building workflows, room to grow | | 11-15 | Advanced | Strong setup, minor optimizations available | | 16-18 | Expert | Boris-level setup 🎯 |

Based On Best Practices From

• Boris Cherny - Creator of Claude Code (his setup)
• Anthropic Docs - Claude Code Best Practices
• Official Documentation - code.claude.com

"Probably the most important thing to get great results out of Claude Code — give Claude a way to verify its work. If Claude has that feedback loop, it will 2-3x the quality of the final result." — Boris Cherny

Contributing

Found a best practice we're missing? Open an issue or PR!

• Add new checks in src/checks/
• Add new templates in templates/
• Follow the patterns in CLAUDE.md

License

MIT © Joe Tannorella