# Improve — AI-Powered Codebase Audit Tool

> Improve audits your codebase with a capable AI model and generates structured improvement plans that cheaper models can execute.

## Install

Save in your project root:

# Improve — AI-Powered Codebase Audit Tool

## Quick Use
```bash
npx @shadcn/improve audit ./src
npx @shadcn/improve plan --output plans/
```

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

---
Source: https://tokrepo.com/en/workflows/asset-8e04902d
Author: AI Open Source