Codebase Optimizer

Systematic AI-driven codebase analysis and refactoring framework for Claude Code.

Achieves 5-11% improvement in code understanding and recommendation quality through repository-specific context engineering.

Quick Start

One-Command Install (Recommended)

# Install agents and tools to your system
npx github:TaylorHonaker/codebase-optimizer init

# Full install (agents + template + config + pre-commit hook)
npx github:TaylorHonaker/codebase-optimizer init --all

# Run analysis on your project
claude "Run codebase-optimizer on src/"

Manual Install (Alternative)

# 1. Clone the repo
git clone https://github.com/TaylorHonaker/codebase-optimizer.git
cd codebase-optimizer

# 2. Run install script
./scripts/install.sh --all

# 3. Run analysis
claude "Run codebase-optimizer on src/"

One-Liner (Full Analysis)

Run this from any repository root for a complete analysis with Best-of-N candidate solutions:

claude --dangerously-skip-permissions -p "Run codebase-optimizer on the entire repository. Generate a full analysis report with Best-of-N candidates for any issues found."

Shell Alias (Optional)

Add to your ~/.bashrc or ~/.zshrc:

alias optimize='claude --dangerously-skip-permissions -p "Run codebase-optimizer on the entire repository. Generate a full analysis report with Best-of-N candidates for any issues found."'

Activate and use:

source ~/.bashrc
cd ~/projects/some-repo
optimize

Requirements

• Claude Code CLI: Install from npm
• Anthropic API Key: Set ANTHROPIC_API_KEY environment variable

Platform Support

| Platform | Support | Notes | |----------|---------|-------| | macOS | Native | All scripts work directly | | Linux | Native | All scripts work directly | | Windows | Via WSL/Git Bash | See Windows Setup Guide below | | Docker | Full | Use bootstrap/docker-compose.yml for sandboxed execution |

Windows Setup Guide

Shell scripts require a Unix-like environment on Windows. Choose one of these options:

Option 1: Git Bash (Recommended)

The easiest option - included with Git for Windows.

1. Install Git for Windows: https://git-scm.com/downloads

   • During installation, select "Git Bash Here" context menu option
   • Select "Use Git from Git Bash only" (safer) or "Use Git from Windows Command Prompt"

2. Open Git Bash and verify:

   bash --version  # Should show 4.x or higher
   git --version   # Verify Git works

3. Run scripts normally:

   cd /c/path/to/codebase-optimizer
   ./scripts/install.sh

Option 2: WSL2 (Best Performance)

For heavy usage, WSL2 provides a full Linux environment.

1. Install WSL2 (run in PowerShell as Administrator):

   wsl --install

2. Restart your computer when prompted

3. Install Ubuntu from Microsoft Store (or use default)

4. Clone repo in WSL filesystem (better performance):

   cd ~
   git clone https://github.com/ai-company-usa/codebase-optimizer.git
   cd codebase-optimizer
   ./scripts/install.sh

Tip: Store repos in WSL filesystem (/home/user/) not Windows filesystem (/mnt/c/) for 10x better I/O performance.

Option 3: Docker (Sandboxed)

Best for automation and isolated execution.

cd bootstrap
docker-compose up

See bootstrap/docker-compose.yml for configuration options.

Common Windows Issues

Issue: ./script.sh: Permission denied

# Fix: Make scripts executable
chmod +x scripts/*.sh

Issue: $'\r': command not found (line ending errors)

# Fix: Configure Git to use Unix line endings
git config --global core.autocrlf input

# For existing files, convert them:
sed -i 's/\r$//' scripts/*.sh

Issue: claude: command not found

# Fix: Ensure npm global bin is in PATH
# Add to ~/.bashrc:
export PATH="$PATH:$(npm config get prefix)/bin"
source ~/.bashrc

Issue: Scripts work in Git Bash but not PowerShell

# PowerShell cannot run .sh files directly
# Always use Git Bash or WSL for shell scripts

What This Does

| Component | Purpose | Impact | |-----------|---------|--------| | CLAUDE.md | Repository-specific context | +5-11% understanding | | Custom Subagents | Specialized analysis tasks | Consistent methodology | | Automation Scripts | Scheduled audits | Zero-maintenance hygiene | | Best-of-N Framework | Multiple solution candidates | Higher quality recommendations |

Repository Structure

codebase-optimizer/
├── bin/                    # CLI entry point (npx support)
│   └── cli.js              # Main executable
├── templates/              # CLAUDE.md templates by stack
│   ├── CLAUDE.md.template  # Base template (start here)
│   ├── CLAUDE-nodejs.md    # Node.js/JavaScript
│   ├── CLAUDE-python.md    # Python
│   ├── CLAUDE-ghl.md       # GoHighLevel + n8n stack
│   └── CLAUDE-remotion.md  # Video pipeline
├── agents/                 # Claude Code custom subagents
│   ├── codebase-optimizer.md
│   ├── dependency-auditor.md
│   ├── security-scanner.md
│   └── performance-profiler.md
├── scripts/                # Automation
│   ├── install.sh          # Setup script
│   ├── weekly-audit.sh     # Scheduled analysis
│   ├── pre-commit-check.sh # Git hook
│   └── generate-report.sh  # Markdown report generator
├── docs/                   # Methodology documentation
│   └── METHODOLOGY.md      # Full framework explanation
├── examples/               # Sample outputs
│   └── audit-report-sample.md
└── package.json            # npm package (enables npx install)

Templates

Base Template

Copy templates/CLAUDE.md.template to your repo root and customize.

Stack-Specific Templates

• Node.js: CLAUDE-nodejs.md - Express, React, async patterns
• Python: CLAUDE-python.md - FastAPI, async, type hints
• GoHighLevel: CLAUDE-ghl.md - GHL API, n8n, Airtable integration
• Remotion: CLAUDE-remotion.md - Video pipeline, audio sync

Custom Agents

Install agents to ~/.claude/agents/:

./scripts/install.sh

Available Agents

| Agent | Invocation | Purpose | |-------|------------|---------| | codebase-optimizer | Full analysis | Comprehensive refactoring roadmap | | dependency-auditor | Dependency check | Outdated/vulnerable packages | | security-scanner | Security audit | Vulnerabilities, secrets, access | | performance-profiler | Performance | Bottlenecks, algorithmic issues |

Usage

# Full analysis
claude "Run codebase-optimizer on src/"

# Dependency audit only
claude "Run dependency-auditor"

# Security scan
claude "Run security-scanner on auth/ and api/"

# Performance profiling
claude "Run performance-profiler on lib/database/"

Automation

Weekly Audit (Recommended)

# Add to crontab (runs Sunday 2 AM)
0 2 * * 0 /path/to/codebase-optimizer/scripts/weekly-audit.sh /path/to/repo

Or Windows Task Scheduler:

.\scripts\Register-WeeklyAudit.ps1 -RepoPath "C:\repos\your-project"

Pre-Commit Hook

# Install hook
cp scripts/pre-commit-check.sh /path/to/repo/.git/hooks/pre-commit
chmod +x /path/to/repo/.git/hooks/pre-commit

Catches:

• Functions >100 lines
• Duplicate code blocks
• Hardcoded secrets patterns
• TODO/FIXME older than 30 days

Methodology

Best-of-N Iterative Analysis

For each identified issue:

1. Generate 3-5 candidate solutions
2. Score each candidate:
   • Performance Impact (40%)
   • Maintainability (30%)
   • Implementation Complexity (-20%)
   • Risk Level (-10%)
3. Recommend highest-scoring option
4. Include alternatives with tradeoffs

Priority Tiers

| Tier | Criteria | Action Timeline | |------|----------|-----------------| | CRITICAL | Security vulnerabilities, >100ms latency, breaking architecture | Immediate | | HIGH | 30%+ performance gain, important updates, structural improvements | This sprint | | MEDIUM | Code quality, minor optimizations, tech debt | This quarter | | LOW | Cosmetic, future-proofing, edge cases | Backlog |

Feedback Loop

After implementing recommendations:

claude "Implemented [recommendation]. Before: [X]. After: [Y]. Calibrate future recommendations."

This trains the system to your codebase patterns.

Integration

CI/CD

# .github/workflows/code-quality.yml
name: Code Quality Check
on: [pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Quick Analysis
        run: |
          claude -p "Check for code smells in changed files: 
          - Functions >100 lines
          - Duplicate code
          - Missing error handling
          Output as PR comment format." --max-turns 3

NotebookLM

Upload weekly audit reports to a "Codebase Health" notebook for:

• Audio overview during commute
• Trend analysis across audits
• Team knowledge sharing

Configuration

Environment Variables

# Optional: Override default settings
export CODEBASE_OPTIMIZER_MAX_ITERATIONS=50
export CODEBASE_OPTIMIZER_OUTPUT_DIR=./docs/audits
export CODEBASE_OPTIMIZER_NOTIFY_SLACK=https://hooks.slack.com/...

Settings File

Create .codebase-optimizer.json in repo root:

{
  "exclude": ["node_modules", "dist", "coverage", ".git"],
  "focus": ["src", "lib", "api"],
  "severity_threshold": "MEDIUM",
  "max_file_size_kb": 500,
  "custom_rules": {
    "max_function_lines": 100,
    "max_file_lines": 500,
    "require_error_handling": true
  }
}

License

MIT - AI Company USA

Contributing

For client deployments, customize templates per engagement.

"Fix reliability before automation. Achieve 100% success rate manually first, then schedule."