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

$3

``bash


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/"
`

$3

`bash


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/"
`

$3

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

`bash
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."
`

$3

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

`bash
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:

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

---

Requirements

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

$3

| 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:

$3

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
bash --version # Should show 4.x or higher
git --version # Verify Git works
`

3. Run scripts normally:
`bash
cd /c/path/to/codebase-optimizer
./scripts/install.sh
`

$3

For heavy usage, WSL2 provides a full Linux environment.

1. Install WSL2 (run in PowerShell as Administrator):
`powershell
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):
`bash
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.

$3

Best for automation and isolated execution.

`bash
cd bootstrap
docker-compose up
`

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

$3

Issue: ./script.sh: Permission denied
`bash


Fix: Make scripts executable


chmod +x scripts/*.sh
`

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


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
`bash


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


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

$3


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

$3

- 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/:

`bash
./scripts/install.sh
`

$3

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

$3

`bash


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

$3

`bash


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:
`powershell
.\scripts\Register-WeeklyAudit.ps1 -RepoPath "C:\repos\your-project"
`

$3

`bash


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

$3

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

$3

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

$3

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

This trains the system to your codebase patterns.

---

Integration

$3

`yaml


.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
`

$3

Upload weekly audit reports to a "Codebase Health" notebook for:
- Audio overview during commute
- Trend analysis across audits
- Team knowledge sharing

---

Configuration

$3

`bash


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/...
`

$3

Create .codebase-optimizer.json in repo root:

`json
{
"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."