Prompt Bouncer Claude Code mod: a Claude Code prompt guard for vague asks

Prompt Bouncer is a community Claude Code prompt guard by Ray Amjad (ray-amjad), published in his claude-code-mods repository. It checks each prompt at the moment you press Enter. If the prompt is vague, it never reaches Claude: you get a toast explaining why, and the text comes back into the prompt box to fix.

The idea, from the README, is that a vague prompt costs a whole turn of Claude guessing, and a wrong guess stays in the context and sometimes in your files. A bounced prompt costs no tokens. The mod has two modes:

• Quick mode (the default) uses no model. A short prompt (15 words or fewer) that leans on phrases such as "the thing", "that bug" or "stuff", or a bare "it" in the first prompt of a session, and names no file, path, code in backticks, quoted name, CamelCase or snake_case word, is bounced.
• Project mode reads your project docs (CLAUDE.md, a glossary, decision records, specs) and asks Haiku whether the prompt is specific and uses your project's words. If not, the toast can suggest the project's own term.

/force <prompt> sends anything past the bouncer, and slash commands always pass. A status line under the prompt shows the current mode.

The install block above adds the author's marketplace and installs the plugin from it. After installing, restart Claude Code or run /reload-plugins. Quick mode is on by default; switch to project mode with /plugin configure prompt-bouncer@claude-code-mods or, for one session, /bouncer project.

The plugin is one function-hooks module, hooks/register.js, listed in hooks/hooks.json. The gate is a hook on prompt.submit that returns { drop } to stop a prompt or next(e) to let it in. This is from register.js:

const verdict = m === 'project'
  ? await projectGate($, text, isFirst, await loadDocs($, options))
  : quickRules(text, isFirst)
if (verdict.pass) return next(e)

bounces += 1
if (!headless) $.ui.toast('Bounced. ' + (verdict.suggestion || verdict.reason), { timeoutMs: 8000 })
return { drop: 'prompt-bouncer: ' + verdict.reason + (verdict.suggestion ? ' Try: ' + verdict.suggestion : '') + ' (Send it anyway: /force <prompt>)' }

Only prompts typed by a person are judged: the hook passes anything whose origin is not the composer, the SDK or the bridge. In project mode the docs are read fresh on every prompt, and one $.model.complete call to Haiku (300 max tokens, 20 second timeout) receives the docs as a cached prefix, then the prompt. /force cannot submit from inside its own command, so it stores the text and a 50 ms timer submits it with $.prompt.submit({ asUser: true }).

The plugin has three options, set with /plugin configure prompt-bouncer@claude-code-mods:

• mode: quick or project.
• docs: the comma-separated files project mode reads, relative to the project root. A * matches file names inside one folder; ** is not supported.
• maxDocChars: docs past this size are cut (default 20000).

The environment variable PROMPT_BOUNCER_MODE overrides mode for one session. Inside a session, /bouncer shows the mode, the bounce count and the docs it found, and /bouncer quick|project|off switches it until the mod reloads. The repository includes an example/ folder, a small invoicing app with a glossary, for trying project mode.

We read every file the plugin can execute or load: plugin.json, hooks/hooks.json and hooks/register.js (169 lines, readable source, no imports, no bundled or minified code, no binaries). The tests and the example/ folder are not loaded by the mod. We found:

• Network: none in the plugin code. In project mode, $.model.complete sends your project docs and the prompt to the Haiku model through Claude Code, the same model path as your session. Quick mode makes no model call.
• Reads files: in project mode only, via $.fs.exists, $.fs.list and $.fs.read, under the session's working directory and only the paths in the docs option. Note that the default list covers CLAUDE.md and your docs folders, and that text is sent to Haiku on every prompt.
• Writes files and runs processes: none. No shell, no child_process, no settings changes, no daemons.
• Environment: reads only PROMPT_BOUNCER_MODE. No secrets, no telemetry.
• Gating: it is a gating hook. It can drop your prompt, and that is exactly what the README says. It has a .catch that passes the prompt through, and project mode fails open. It cannot block tool calls and does not rewrite prompts, except removing a leading !. It injects no text into Claude's context.
• Commands: registers /bouncer and /force. /force re-submits your own text with $.prompt.submit.
• License: MIT, with a LICENSE file in the repository.

claude plugin validate passed on Claude Code 2.1.307 with no errors. It reported one non-blocking directory warning, no plugin icon, which does not affect use. claude plugin test ran 9 tests (2 files) on 2.1.307 and all passed.

We tested commit 6db48a3 on Claude Code 2.1.307; the author's README says it was tested with 2.1.296. The mod needs function hooks. In claude -p and SDK sessions the drop still applies, but no status line or toast is drawn.

• A prompt was bounced that you wanted to send: run /force <prompt>. Quick mode's word lists are short and English only, and in project mode Haiku sometimes misjudges.
• Project mode does nothing useful: run /bouncer and check "Project docs". If it says none found, the files in docs do not exist relative to the folder where Claude Code is running.
• Project mode is slow: it adds one Haiku call (a few seconds) to each prompt. Switch to /bouncer quick or lower maxDocChars.
• The mode resets: /bouncer overrides last only for the session and reset when the mod reloads. Use the mode option for a permanent choice.

To check it works, type fix the thing as the first prompt of a session. It should be dropped with a toast.