What is prompt-refiner?
prompt-refiner is a Claude Code hook that turns a rough prompt into a more specific instruction before the main agent receives it. It sends the prompt and a recent extract of the session transcript to a fresh headless Claude, then displays and copies the refined prompt for you to review. It is intended for Claude Code users who want their requests to account for work already done in the session. A second mode can send the refined prompt straight to the main agent.
prompt-refiner Features:
Session Context: For prompts beginning with ++, the hook sends the rough request along with a tail extract of the current session transcript to a fresh Claude.
Prompt Refinement: The refiner returns a single paragraph guided to include the goal, file anchors, constraints, deliverable, and verification.
Review Before Sending: In the standard mode, the hook copies the result to the clipboard, blocks the rough prompt, and shows the refined text on screen.
Direct Execution: Adding an exclamation mark after ++ runs the refined version through the main agent without showing it to you first.
Editable Instructions: You can change prompts/refiner.md to adjust how requests are refined, including the guidance to preserve your language, voice, and intent.
Run Diagnostics: The hook stores the last refined prompt, submitted payload, run log, and error output in its state directory.
prompt-refiner Benefits:
Clearer Requests: Adding goals, constraints, and verification steps can make it easier for the coding agent to understand what a task should accomplish.
Less Repetition: Using recent transcript context can help turn a short follow-up into an instruction that reflects what has already happened in the session.
More Control: The review-first flow lets you edit the refined wording before the main agent acts on it.
Focused Context: A separate Claude handles refinement, so the main agent does not receive the rough prompt or the refiner's reasoning.
Easier Troubleshooting: Saved payloads and run details give you material to inspect when a refinement is weak or the hook encounters an error.
Use Cases:
Repairing a Test: After a test run reports a failure, type a short request such as “fix the broken test” and let the refiner draw on the session details.
Follow-Up Changes: Use a brief instruction for the next code change when the relevant files or task decisions have already appeared in the conversation.
Adding Verification: Refine a coding request when you want its resulting instruction to include a check, such as running the relevant tests.
Reviewing Before Action: Choose the standard mode for a consequential coding task when you want to inspect and adjust the agent's instruction before sending it.
Fast Prompt Handoff: Use the ++! mode for a task where you prefer the refined prompt to go directly to the main agent without an intermediate review.

