Today v0.5.3 of the Claude Code Prompt Improver shipped. The project is past 1.4K GitHub stars, and this update fixed two problems that were burning tokens and bloating plans without you noticing. Both fixes are the kind you don’t realize you needed until someone shows you how much waste was happening in the background.
What the plugin actually does
It’s a UserPromptSubmit hook that intercepts every prompt before Claude sees it. If the prompt is clear, it passes straight through. If it’s vague, the plugin researches your codebase and asks you 1 to 6 clarifying questions before Claude writes a single line. About 189 tokens overhead per prompt, and only when the skill actually fires.
Think about what “vague” means here. Something like “fix the auth bug” or “make the dashboard faster”, prompts that any experienced developer would push back on before touching a keyboard. The plugin handles that pushback automatically. It looks at your actual file structure, reads relevant context, and turns your fuzzy intent into a specific brief. The questions aren’t generic either. They’re grounded in what’s actually in your repo: which auth module, which dashboard component, what metric you mean by “faster.” You answer, Claude gets a real spec, and the output you get back is useful the first time instead of the third.
The twist: your plans were silently bloating
When Claude revises a plan, it tends to keep its reasoning trail. Phrases like “previously I considered X but rejected it because Y” stack up. By revision three you’re scrolling past decision archaeology to find what actually needs to happen next.
This is subtle enough that most people don’t notice it until their plans are five revisions deep and completely unreadable. What should be a clean list of next actions turns into a history document. And because Claude is reading the whole thing on every revision, you’re also paying for it in tokens and latency. The bloat is invisible until it isn’t.
v0.5.3 adds a new hook that fires on EnterPlanMode and gives Claude a clean-rewrite contract:
- 🧹 Keep the problem statement, strip all decision history
- 📝 On revision, rewrite the full plan clean. No appending, no annotating.
- 📍 One action per step. Use file paths as anchors: src/auth.ts:42
- Short action steps only. Not explanations.
One commenter put it well: “Decision history belongs in the chat, not the plan doc.” That’s the principle the hook encodes. The chat is the right place for reasoning. The plan is for execution. These two things kept getting mixed together, and the hook separates them cleanly. If you’ve ever opened a revised plan and had to read three paragraphs before finding the first concrete step, you know exactly what this fix addresses.
The second fix: research was burning main-context tokens
v0.5.2 changed where codebase research runs when a prompt is vague. Previously, Glob, Grep, and WebSearch all ran in the main context, using main-model tokens. Now that work gets dispatched to Task/Explore subagents on Haiku in a separate context window. The main context handles only synthesis and the question to the user. Lighter, faster, cheaper.
The practical difference is real. Haiku costs significantly less per token than Sonnet or Opus, and running file searches and grep operations in a separate context means none of that intermediate noise lands in your main conversation window. The main model gets a clean summary: here’s what the codebase looks like, here are the relevant files, here’s the question to ask. No trace of the search work left behind. For teams running dozens of Claude Code sessions a day, this kind of architectural improvement compounds quickly into meaningful cost savings.
How to install it ⚡
- Run:
claude plugin marketplace add severity1/severity1-marketplace - Then:
claude plugin install prompt-improver@severity1-marketplace - The hook activates automatically on your next Claude Code session
If you want to verify it’s working, fire a deliberately vague prompt at Claude right after installing. Something like “improve performance” with no other context. You should see clarifying questions come back before any code gets generated. That’s the hook doing its job.
Pro tip
The plan mode wording is still being refined and the author is actively asking for feedback. If plan bloat has been a recurring problem in your workflow, test this and share what you find. Your edge case might shape the next version. Specifically worth testing: projects with complex multi-file refactors, or any workflow where you’re doing multiple planning rounds before execution. Those are the scenarios where decision archaeology gets worst fastest, and where a clean-rewrite contract makes the biggest difference in day-to-day speed.
Grab the repo: github.com/severity1/claude-code-prompt-improver 🔗
Frequently Asked Questions
Q: Why did the plugin start forcing plans to be rewritten instead of updated?
Plans were accumulating decision history and rejected ideas each time Claude revised them, getting bloated and hard to follow. The new rule forces a full rewrite on each revision, drop the history, keep only the current plan. One commenter had the same issue and found decision history just clutters the planning document.
Q: What’s the benefit of moving research to subagents?
Searching your codebase used to burn tokens in the main context. Now that work runs in Task/Explore with Haiku (a cheaper model with its own token budget). Your main context stays free for synthesis and talking to you, so you’re not burning expensive tokens on lookups.
Q: Why should decision history be in chat, not in my plan?
Decision history in plans compounds over revisions and makes them hard to read. Keep it in the chat conversation where it belongs. Plans should be clean action steps with file paths, the chat is where you explore the thinking behind those steps.
Q: Does this plugin work on Windows now?
Yes. Earlier versions hardcoded python3, which doesn’t exist by default on Windows. v0.5.3 adds fallback logic (python3 || python), so the hook works on both Unix and Windows systems.
Claude Code Prompt Improver v0.5.3 — plan mode readability + subagent-first research
by u/crystalpeaks25 in PromptEngineering