# Bouncer

> Bouncer is a free, open-source hook for Claude Code and OpenAI Codex. It stops prompts that waste tokens (Opus on small tasks, bloated context, leaked secrets, huge pastes, vague asks) and rescues your session at the 5-hour limit.

Bouncer is a set of hooks (UserPromptSubmit, Stop, SessionStart, PostModelSwitch) installed by `bouncer init`. It checks each prompt before Claude Code or Codex sends it. It never edits code or prompts: it lets a prompt through with a short advisory note, or stops it and puts the prompt (or a handover) on the clipboard with one clear next step. Ending a prompt with " !" skips every check except secret blocking. It runs offline by default; a free AI (Cloudflare Workers AI, Groq, Gemini, Ollama) is optional and only asked when a decision depends on it.

Key facts:
- Free and open source (MIT). Version 0.1.0, installed from source: https://github.com/quyvh20/BOUNCER
- Requirements: Node.js 18.17+, git, Claude Code v2.1.251+ (CLI, desktop Code tab, VS Code, JetBrains) or OpenAI Codex. Not supported: Cursor, Gemini CLI, Antigravity, claude.ai chat.
- Biggest saving: eco mode (`bouncer eco on`). In 144 measured sessions 77% of cost was re-reading context; keeping it under 200k gives up to 44% lower cost.
- Model advice: TRIVIAL → Haiku/low, STANDARD → Sonnet/medium, COMPLEX → Opus/high. Hooks cannot switch models; Bouncer tells the user the command.
- Savings shown are estimates; `bouncer measure on` measures real savings with an A/B test.

## Start here

- [Installation & Requirements](https://quyvh20.github.io/BOUNCER/guide/installation): Requirements, supported tools (Claude Code, Codex), per-OS install, troubleshooting.
- [Getting Started](https://quyvh20.github.io/BOUNCER/guide/getting-started): The after-answer report, eco mode, model advice, A/B measurement, commands, modes, block messages.
- [FAQ](https://quyvh20.github.io/BOUNCER/guide/faq): Why a prompt was blocked, how to send it anyway, whether it saves tokens, privacy, speed.

## How it works

- [Safety Architecture](https://quyvh20.github.io/BOUNCER/guide/safety-architecture): The evaluation pipeline, the 5 safety laws and the quality guards.
- [Rate-Limit Rescue](https://quyvh20.github.io/BOUNCER/guide/vip-evacuation-rescue): The git-backed handover built when the 5-hour limit hits.
- [CLAUDE.md Templates](https://quyvh20.github.io/BOUNCER/guide/claude-md-templates): Copy-paste CLAUDE.md and .claudeignore rules that cut token use.

## Optional AI setup

- [Bronze vs Silver vs Gold](https://quyvh20.github.io/BOUNCER/unlock-gold/): What connecting a free AI adds.
- [Recommended models](https://quyvh20.github.io/BOUNCER/unlock-gold/recommended-models): Measured benchmark of 14 models.
- [Cloudflare Workers AI](https://quyvh20.github.io/BOUNCER/unlock-gold/cloudflare-workers-ai): Free setup, default Mistral Small 3.1.
- [Groq](https://quyvh20.github.io/BOUNCER/unlock-gold/groq-70b-free): Free Llama 3.3 70B.
- [Gemini](https://quyvh20.github.io/BOUNCER/unlock-gold/gemini-flash-free): Free Gemini 2.5 Flash.
- [Ollama](https://quyvh20.github.io/BOUNCER/unlock-gold/ollama-local): 100% offline.

## Trust

- [About](https://quyvh20.github.io/BOUNCER/about): Who builds it, how the numbers were measured, honest limits.
- [Privacy & Security](https://quyvh20.github.io/BOUNCER/privacy): What is read, stored and sent; API keys; reporting vulnerabilities.
- [Changelog](https://quyvh20.github.io/BOUNCER/changelog): Notable changes.
- [Send feedback](https://quyvh20.github.io/BOUNCER/feedback): Report a wrong block, a bug or an idea on GitHub.

## Optional

- [Full documentation in one file](https://quyvh20.github.io/BOUNCER/llms-full.txt)
- [Source code](https://github.com/quyvh20/BOUNCER)