Improve — AI-Powered Codebase Audit Tool

Introduction

Improve is a developer tool that uses a high-capability AI model to deeply analyze a codebase and produce structured improvement plans. These plans are designed to be executed by faster, cheaper models, creating an efficient two-tier workflow.

What Improve Does

• Scans a codebase to identify code quality issues, dead code, and architectural debt
• Generates structured improvement plans in Markdown with precise file references
• Prioritizes findings by impact and effort
• Produces plans consumable by AI coding agents for automated execution
• Supports incremental audits focused on recently changed files

Architecture Overview

Improve works in two phases. The audit phase feeds source files to a frontier AI model with specialized prompts that evaluate code quality, consistency, and architecture. The plan phase synthesizes findings into self-contained task descriptions with enough context for an AI coding agent to execute without additional human guidance.

Self-Hosting & Configuration

• Install via npx or npm with Node.js 18+
• Configure AI provider and model via environment variables
• Target specific directories or file patterns for focused audits
• Output plans to a directory for batch processing by agents
• Integrates with CI pipelines for periodic health checks

Key Features

• Two-tier model strategy: expensive model audits, cheap model executes
• Structured plan output with file paths, line references, and rationale
• Priority scoring based on impact and complexity
• Incremental mode for auditing only changed files
• Works with any OpenAI-compatible or Anthropic API

Comparison with Similar Tools

• SonarQube — Rule-based static analysis; Improve uses AI for deeper semantic understanding
• CodeClimate — Focuses on metrics; Improve generates actionable plans
• PR-Agent — Reviews individual PRs; Improve audits entire codebases holistically
• Sourcery — Suggests inline refactorings; Improve plans larger cross-file improvements

FAQ

Q: Does it modify code directly? A: No. Improve only produces audit reports and plans.

Q: What AI models does it support? A: Any OpenAI-compatible or Anthropic API.

Q: Can I run it in CI? A: Yes, as a CI step to track codebase health over time.

Q: How large a codebase can it handle? A: It processes files incrementally, limited mainly by API token budgets.

Sources

• https://github.com/shadcn/improve