scope-guard

Scope Guard

"Add email OTP login" becomes a 12-file authentication framework. "Fix this type error" somehow requires restructuring half your app.

Sound familiar?

Scope Guard is a Claude Code plugin that detects when your AI coding agent goes beyond what you asked for - and stops it before completion.

---

The Problem

This is the #1 complaint in the Claude Code community:

You: "Fix the typo in README.md"

Claude: *fixes typo*
        *adds author to package.json*
        *creates src/utils/helpers.js*
        *updates CHANGELOG.md*
        *refactors imports "while I'm here"*

You: "I just wanted the typo fixed..."

Real issues from the community:

• Claude makes destructive unauthorized changes - "Asked to fix 1 service, broke 17 of 21"
• Over-Engineering bug - "Turning 3 products into 6+"
• Violates refactoring principles - "Changes behavior during refactoring"

---

The Solution

┌─────────────────────────────────────────────────────────────────┐
│  YOU: "Fix the login validation bug"                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  CLAUDE TRIES TO:                                               │
│  ├── Edit src/auth/login.ts           ← Related to request     │
│  ├── Edit src/auth/register.ts        ← NOT requested          │
│  ├── Create src/events/event-bus.ts   ← NOT requested          │
│  └── Edit package.json (new dep)      ← NOT requested          │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  SCOPE GUARD:                                                   │
│                                                                 │
│  ❌ BLOCKED - Scope creep detected                              │
│                                                                 │
│  • register.ts: Changes to registration flow not requested      │
│  • event-bus.ts: New event system not part of bug fix           │
│  • package.json: Added dependency without approval              │
│                                                                 │
│  Original task: "Fix the login validation bug"                  │
│  Only login.ts changes are justified.                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Install

Inside Claude Code:

/plugins add https://github.com/andreahlert/scope-guard

That's it. Zero config. Zero API keys. Zero dependencies.

---

How It Works

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│    SUBMIT    │    │    TRACK     │    │   EVALUATE   │
│    PROMPT    │───▶│    CHANGES   │───▶│   AT STOP    │
└──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
  Captures your      Silently logs       Compares prompt
  original request   every file edit     vs actual changes
  + git commit       in background       using git diff

Three hooks, two scripts, zero magic:

Hook	Script	What it does
UserPromptSubmit	capture-prompt.js	Saves your prompt to session.json
PostToolUse	track-change.js	Logs each Edit/Write to changes.log
Stop	Agent hook	Runs git diff, evaluates scope alignment

The Evaluation Rules

The Stop hook asks one question for each changed file:

"Is this file EXPLICITLY mentioned in the prompt?"
    │
    ├── YES → Check if changes match what was asked
    │
    └── NO  → Is it OBVIOUSLY required? (imports, types, tests)
                  │
                  ├── YES → Allow
                  └── NO  → SCOPE CREEP

Critical rule: Same folder ≠ related. "Change Header" does NOT permit Footer changes.

---

Examples

Acceptable Changes