Improve — AI-Powered Codebase Audit and Plan Generator

Introduction

Improve is a developer tool created by the shadcn team that leverages expensive, highly capable AI models to analyze your codebase and produce structured improvement plans. These plans are precise enough for smaller, cheaper models to execute autonomously, saving significant costs on iterative development.

What Improve Does

• Scans your codebase and identifies areas for improvement
• Generates detailed, step-by-step execution plans in markdown
• Plans are structured so less capable models can follow them precisely
• Covers code quality, architecture, performance, and accessibility
• Produces actionable tasks rather than vague suggestions

Architecture Overview

Improve works as a two-phase system. In the audit phase, it sends your code to a high-capability model that produces a structured analysis with specific improvement recommendations. In the plan phase, it converts these recommendations into precise, file-level instructions that any coding agent can execute without ambiguity.

Self-Hosting & Configuration

• Install via npm or run with npx for zero-install usage
• Configure your preferred AI provider via environment variables
• Supports OpenAI, Anthropic, and local model endpoints
• Output plans to markdown files or pipe to other tools
• Customize audit scope with .improveignore patterns

Key Features

• Two-tier cost optimization: expensive model plans, cheap model executes
• Outputs are deterministic enough for automated application
• Supports monorepos and multi-language projects
• Integrates with existing CI/CD for automated improvement proposals
• Plans include verification steps so the executor can self-check

Comparison with Similar Tools

• GitHub Copilot — inline suggestions vs structured project-wide audits
• SonarQube — rule-based linting vs AI-driven architectural insights
• Sourcery — Python-focused refactoring vs language-agnostic planning
• PR-Agent — PR-scoped review vs full-codebase improvement planning
• Codemod — migration-focused vs broad improvement coverage

FAQ

Q: Which models work best for the audit phase? A: The tool is optimized for frontier models like Claude or GPT-4 class for auditing, and can target any model for execution.

Q: Does it modify my code directly? A: No. It generates plans only. You choose when and how to apply them, manually or via an agent.

Q: How large a codebase can it handle? A: It processes files incrementally and supports repos of any size through chunked analysis.

Q: Is my code sent to external APIs? A: Yes, during the audit phase. You can use local models if privacy is a concern.

Sources

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