cuttheyap

CutTheYap

"Catch vague prompts before Claude acts on them — and sharpen them into precise, context-aware ones."

A local UserPromptSubmit gate for Claude Code that detects low-signal prompts and returns a tiered clarification — pure-local, no LLM, no network.

What is this

Vague prompts make Claude guess: it picks a target, burns turns on the wrong thing, and you spend the next few messages correcting it. CutTheYap intercepts each prompt locally, scores its clarity, and — only when it looks vague — asks for the missing specifics before Claude acts. Clear prompts pass straight through, untouched, with zero added latency. The gate is fail-open by design: if anything errors or python3 is absent, your prompt proceeds normally.

Features

• Pure-local — no LLM call, no network, no telemetry. Runs as a Python hook on your machine.
• Zero-latency on clear prompts — the gate stays out of the way when the prompt is already specific.
• Tiered response — classifies vagueness as low / medium / high and scales the clarification accordingly.
• Bilingual detection — works on English and Italian prompts, including Italian enclitic-pronoun imperatives (sistemalo, aggiustala).
• On-demand rewriting — a read-only prompt-improver agent drafts a precise rewrite and never edits your files.
• Fail-open by design — any error or missing python3 lets the prompt through unchanged.
• 77 passing tests — behavior validated by a 6-scenario automated A/B battery.

Quick Start

In an interactive Claude Code session (slash commands):

/plugin marketplace add francesco-delrosso/CutTheYap
/plugin install cuttheyap@cuttheyap

Or from the claude CLI:

claude plugin marketplace add francesco-delrosso/CutTheYap
claude plugin install cuttheyap@cuttheyap

The marketplace name and the plugin name both resolve to cuttheyap, so cuttheyap@cuttheyap is correct.

Usage

After install, the gate runs automatically on every prompt — there is nothing to invoke. A vague prompt triggers a tiered clarification before Claude acts; a clear, well-targeted prompt passes through with no added output.

For on-demand rewriting, invoke the read-only agent directly:

/cuttheyap:prompt-improver

It researches the relevant project context and returns an improved prompt plus 1-3 clarifying questions, without touching your files.

Before / after

A vague prompt elicits a clarification instead of a guess:

> fix it
→ Claude asks: which file or symbol is broken, and what is the expected behaviour?
  e.g. "Fix the off-by-one in parse_range() in src/ranges.py so an empty input
  returns []." It confirms the rewrite with you, then proceeds.

You can watch the gate decide for yourself. It reads a JSON payload on stdin and prints an additionalContext injection only when the prompt is vague:

# Clear prompt -> no output, prompt proceeds untouched
$ echo '{"prompt": "add a --version flag to hooks/gate.py that prints the version"}' | python3 hooks/gate.py
$

# Vague prompt -> tiered clarification injected
$ echo '{"prompt": "fix it"}' | python3 hooks/gate.py
{"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "[CutTheYap] This prompt looks very ambiguous (signals: action-without-target, vague-reference, very-short). Before acting: dispatch the `prompt-improver` agent to research the project context and draft an improved prompt plus 1-3 clarifying questions. Ask the user those questions, show the proposed rewrite, get confirmation, then proceed. If the agent is unavailable, rewrite inline and confirm instead."}}

Configuration

CutTheYap works out of the box with no configuration. If you want to adjust it, four environment variables are read defensively by hooks/gate.py — a missing or invalid value falls back to the default and never breaks the gate:

Variable	Default	Effect
CUTTHEYAP_DISABLE	(unset)	1 / true / yes / on turns the gate into a no-op.
CUTTHEYAP_BYPASS	raw:	Prompt prefix that skips the gate entirely.
CUTTHEYAP_MEDIUM_AT	2	Point threshold for the medium tier.
CUTTHEYAP_HIGH_AT	3	Point threshold for the high tier.

Lower the thresholds to be more sensitive, raise them to be quieter. Start any prompt with raw: (or your custom CUTTHEYAP_BYPASS prefix) to skip the gate for that one prompt.

Repository Structure