Boris Mode 🎯

Are you using Claude Code effectively? This tool will audit your setup and tell you exactly how to improve.

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

Boris Mode runs through a series of heuristic checks to audit your setup (are you using hooks? MCPs? Slash commands? etc.), uses Claude Code to actually analyze your claude code history, and then provides a report with actionable recommendations.

The output includes a markdown document that can be used to guide you through the improvements, or you can run the --apply command to generate a prompt that Claude Code can use to apply the fixes for you automatically.

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

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 boris-mode

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 | | MCP Servers | MCP tools configured (Context7, Playwright, etc.) |

Prompting Habits (opt-in, requires consent)

| Category | What We Look For | | -------------------- | ------------------------------------------------------ | | Prompting Habits | Prompt length, plan mode usage, anti-pattern detection |

🔒 This check analyzes your Claude Code session data in ~/.claude/. You'll be asked for consent before any analysis runs. Use --skip-prompts to skip entirely.

Deep Analysis (default)

| 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 | | Prompting Habits Quality | Outcome clarity, context provision, verification mindset (requires consent) |

Example Output

🎯 Boris Mode v0.1.3

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   │
│ MCP Servers         │ ⚠️      │ 1/2   │
│ Prompting Habits    │ ─      │ ─     │
├─────────────────────┼────────┼───────┤
│ Overall             │ Interm │ 6/14  │
└─────────────────────┴────────┴───────┘

📄 Full report: .boris-mode/report.md
🚀 Auto-apply:   npx boris-mode --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 boris-mode --apply

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

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

CLI Options

npx boris-mode [options]

Options:
      --no-deep            Skip AI-powered deep analysis for faster results
  -t, --timeout <secs>     Timeout per deep check (default: 120)
  -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: .boris-mode)
  -j, --json               Output as JSON (for CI/tooling)
  -p, --path <path>        Path to project (default: current directory)
      --skip-prompts       Skip prompting habits analysis (no consent prompt)
  -y, --yes                Auto-accept all prompts (non-interactive mode)
  -V, --version            Show version
  -h, --help               Show help

Deep Analysis Mode

By default, Boris Mode uses the Claude CLI to analyze the quality of your setup, not just check if files exist:

• 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?
• Prompting habits quality - Are you writing effective prompts? (opt-in, requires consent)

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

For faster scans without AI analysis (e.g., in CI or when the Claude CLI is unavailable):

npx boris-mode --no-deep

Prompting Habits Analysis

Boris Mode can analyze your Claude Code session history to evaluate your prompting patterns. This is opt-in and requires explicit consent since it reads data from ~/.claude/.

What it checks:

• Prompt length - Are your prompts detailed enough? (median ≥50 characters)
• Feature usage - Are you using plan mode or extended thinking?
• Anti-patterns - Are you sending vague prompts like "fix this" or "help"?

Deep analysis evaluates:

• Outcome clarity - Do your prompts clearly state what you want?
• Context provision - Do you provide enough background?
• Constraint specification - Do you define boundaries and requirements?
• Verification mindset - Do you ask Claude to verify its work?
• Decomposition skill - Do you break complex tasks into steps?

Privacy controls:

# Skip prompting analysis entirely (no consent prompt)
npx boris-mode --skip-prompts

# Auto-accept consent (for CI/automation)
npx boris-mode --yes

Scoring

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

Core checks max: 20 points (14 static + 6 deep). With prompting habits analysis: +7 points (4 static + 3 deep).

With --no-deep (static checks only), max score is 14 points (or 18 with prompting habits).

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!

Joe Tannorella