Improve: Use Your Best AI Model to Audit Codebases and Write Plans for Cheaper Agents to Execute
Improve: Use Your Best AI Model to Audit Codebases and Write Plans for Cheaper Agents to Execute
AI coding agents are transforming how we write software, but there's a problem. Running your most powerful model (Opus, GPT-4.8, Gemini Ultra) on every small change is expensive, slow, and wasteful. The smaller models are cheap and fast, but they lack the architectural judgment to plan complex changes on their own.
shadcn/improve — from the creator of shadcn/ui — solves this with a clean architectural split. Your most capable model audits the codebase, understands the architecture, and writes detailed implementation plans. Cheaper models then execute those plans in isolated worktrees. The result: Opus-level architecture decisions at GPT-4o-mini execution prices.
With 3,654+ GitHub stars in just 4 days, improve is one of the fastest-growing developer tools of June 2026. It's open-source under MIT, self-hosted, and works with any agent that supports the Agent Skills format.
Architecture
The workflow is structured around a clear separation of concerns:
-
Advisor (expensive model): Runs the
/improvecommand. Maps the repo structure, fans out parallel audit subagents across 9 categories (correctness, security, performance, test coverage, tech debt, dependencies, DX, docs, feature direction), vets every finding by re-reading cited locations, prioritizes by leverage (impact ÷ effort), and writes self-contained plan files intoplans/. -
Plans Directory: Each plan is a standalone markdown file with current-state code excerpts, exact steps, verification gates (commands + expected output), and hard STOP conditions. Plans are written for the weakest plausible executor — any model (or human) can pick one up.
-
Executor (cheap model): Runs
/improve execute <plan>in an isolatedgit worktree. Follows the plan step by step, runs every verification gate, and reports back. The advisor reviews the resulting diff against the plan — approve (merging stays your call), send back for revision (max 2 rounds), or block and refine the plan.
Why It's Trending
Three forces make improve take off:
-
The model price gap is widening. Claude Opus 4.8 costs ~$75/M input tokens while Haiku 3.5 costs ~$0.80/M. Using Opus to plan and Haiku to execute gives you nearly identical output quality at 1% of the cost.
-
Agent interoperability is emerging. The Agent Skills format lets skills like improve run in Claude Code, Codex, Cursor, and any OpenHands-compatible agent. The plans improve writes are plain markdown — any tool can read them.
-
AI-generated code needs review. improve bakes the review into the workflow. The advisor re-reads every cited location during audit, the executor is reviewed after execution, and the
reconcilecommand verifies nothing drifted between sessions.
Prerequisites
- Node.js 18+ (for
npx skills add) - An agent that supports Agent Skills — Claude Code, Codex, Cursor, or any OpenHands-compatible agent
- Git (for worktree isolation during plan execution)
- A capable LLM API key (Claude, OpenAI, Gemini — whichever you use for your agent)
- The skill itself:
npx skills add shadcn/improve
Installation and Setup
1. Add the Skill
npx skills add shadcn/improveThis downloads the skill to your agent's skills directory.
2. Verify Installation
In your agent, run:
/improve quickIf the skill is loaded correctly, it will perform a quick pass of your current repository — mapping the stack, running a lightweight audit, and presenting findings.
3. First Full Audit
For a comprehensive analysis:
/improveThis runs the full pipeline: recon → audit (9 categories) → vet → prioritize. After ~30-60 seconds (depending on repo size), you'll see a findings table:
| # | Finding | Category | Effort | Confidence |
|---|----------------------------------------|-----------|--------|------------|
| 1 | Shadow config duplicated in 3 files | tech-debt | M | HIGH |
| 2 | O(n²) icon migration loop | perf | S | HIGH |4. Generate Plans
Reply with the findings you want planned:
plan 1, 3 and 5The skill writes one markdown file per finding into plans/, plus an index file with the recommended execution order.
5. Execute a Plan
/improve execute 001This creates an isolated git worktree, spawns a cheaper model, hands it the plan, and reviews the result. It never touches your working tree directly — merging is always yours.
6. Daily Reconcile
Before starting new work:
/improve reconcileThis checks what's landed since the last session, refreshes plans that drifted, and retires findings that got fixed independently.
Advanced Usage
Focused Audits
/improve security # Security-focused audit only
/improve perf # Performance hotspots
/improve tests # Test coverage gaps
/improve branch # Audit only what your current branch changesSkip Audit, Plan Directly
If you already know what you want done:
/improve plan "Extract the payment gateway into a separate module"Review an Existing Plan
/improve review-plan plans/003-refactor-auth.mdPublish Plans as GitHub Issues
/improve ... --issuesThis publishes every plan as a well-formatted GitHub issue — self-contained, with file paths, code excerpts, and verification gates.
How It Works: Under the Hood
The skill uses a multi-stage pipeline:
Recon. Reads your repo's stack, conventions, and exact build/test/lint commands. It also ingests intent docs (ADRs, PRDs, DESIGN.md) so decided tradeoffs aren't re-flagged as findings.
Audit. Fans out parallel subagents across 9 categories. Each subagent has expertise in its domain — the security subagent knows OWASP patterns, the perf subagent looks for N+1 queries and memory leaks.
Vet. The advisor re-reads every cited location itself before presenting findings. False positives get dropped with recorded reasons (so they don't return next run).
Prioritize. Findings are scored by leverage: (impact × confidence) ÷ effort. The highest-leverage items appear first.
Plan. Each plan file contains:
- File paths with current-state code excerpts
- Step-by-step implementation instructions
- Verification gates with expected output
- Hard STOP conditions
- The git commit hash it was written against
Execute. Creates a disposable worktree, runs the plan through a cheaper model, checks the diff against the plan's criteria, and reports a verdict.
Comparison with Alternatives
- GitHub Copilot Workspace: Proprietary, cloud-only, less granular control over which model audits vs. executes. improve is open-source and self-hosted.
- OpenHands / OpenDevin: Full coding agent, not a plan-first workflow. improve focuses on planning and lets you mix and match executors.
- Cursor Agent: Tied to Cursor IDE. improve works with any agent (Claude Code, Codex, Cursor, or plain terminal).
- Aider: Excellent for pair programming, but doesn't have the plan-audit-execute separation that improve brings.
Resources
- GitHub Repository: github.com/shadcn/improve
- Agent Skills Format: agentskills.io
- Author: shadcn — creator of shadcn/ui
- License: MIT