Scope Bouncer

Scope Bouncer helps vibe coders keep AI coding agents on mission.

It sits beside tools like Claude Code and Codex. When a prompt or tool call starts drifting into extra features, polish, or "while we're here" work, Scope Bouncer asks:

Which must-ship outcome does this unblock?

Prompts get friendly warnings. Risky edits and shell actions can be stopped before they happen. Everything stays local: no Scope Bouncer account, server, or database.

npm * Setup guide * Issues * Privacy

How Protection Works

Scope Bouncer is opt-in per project.

Turning hooks on in Codex or Claude only makes Scope Bouncer available. It does not protect every chat or every folder on your computer.

A folder is protected only after you set it up with Scope Bouncer and add a local SCOPE.md.

Scope Bouncer is optimized for projects that live in local folders. It does not protect chat-memory-only projects unless that chat is working from a folder with SCOPE.md.

Global hooks on = Scope Bouncer can listen
Project setup done = Scope Bouncer enforces scope
No project setup = Scope Bouncer stays quiet

Install In 30 Seconds

Open Terminal in the project folder you want to protect.

Codex Desktop:

npx scope-bouncer setup codex

Claude Code:

npx scope-bouncer setup claude

Both:

npx scope-bouncer setup both

First run starts the onboarding wizard and creates SCOPE.md in draft mode. This file is the scope contract for that project.

Open SCOPE.md, make the mission true, then change:

Scope Status
Draft - edit this file, then change this line to Active.

to:

Scope Status
Active

Then run the same setup command again:

npx scope-bouncer setup codex

That second run installs the hooks for this project.

If you prefer installing once and reusing the command everywhere:

npm install -g scope-bouncer
scope-bouncer setup codex

If your computer says npm or npx is missing, install Node.js LTS from nodejs.org, then run the command again.

Reset a project to a clean Scope Bouncer state:

npx scope-bouncer reset

Codex Desktop Extra Step

Codex Desktop requires one manual permission step after setup.

Open Settings -> Hooks, select your project folder, and turn on every Scope Bouncer toggle for both PreToolUse and UserPromptSubmit.

Codex will not run hooks until those toggles are on.

Check It Is Working

Run:

npx scope-bouncer status

Status means:

• Protected here: Scope Bouncer is installed and has recent hook activity.
• Partly protected: setup exists, but something still needs attention.
• Not protected here: this folder has not been set up yet.

For a deeper check:

npx scope-bouncer doctor codex
npx scope-bouncer doctor claude

What It Does

• Keeps the original mission visible while you build.
• Warns when prompts drift into extras.
• Blocks risky tool calls before edits happen.
• Lets you justify intentional scope changes with two questions.
• Logs decisions locally so you can see where the project tried to drift.

Supported Surfaces

| Surface | Prompt warnings | Tool-call blocking | Status | |---|---:|---:|---| | Claude Code | Yes | Yes | Ready | | Codex | Yes | Yes | Ready, with manual hook permission step | | CLI / scripts | Manual | Manual | Ready | | Cursor / Windsurf / Aider | No | No | Planned | | Browser chat | No | No | Research only |

Useful Commands

npx scope-bouncer status
npx scope-bouncer report
npx scope-bouncer report --digest
npx scope-bouncer reset

reset removes Scope Bouncer hooks. It leaves SCOPE.md and decision history in place.

Docs

• Full setup guide
• Codex hooks
• Claude Code hooks
• Roadmap
• Privacy
• Security
• Contributing

License

MIT