Opus Guard

Save ~2.7x tokens on Claude Code by routing research agents to Sonnet while keeping code writing on Opus.

The Problem

Claude Code subagents inherit Opus by default. A web search costs 47K tokens on Opus vs 17K on Sonnet — you're overpaying for tasks that don't need Opus quality.

What It Does

Agent	Model	Scope
Explore	Sonnet	Codebase read/search
researcher	Sonnet	Web research
general-purpose	Sonnet	Multi-step research
coder	Opus	Code writing/editing
Main conversation	Opus	Everything

4-layer protection:

1. Agent files — pin research agents to Sonnet by default
2. PreToolUse hook — blocks WebSearch/WebFetch in Opus session, prevents model override
3. settings.json matchers — activates the hook for Agent, WebFetch, WebSearch
4. CLAUDE.md rules — behavioral guardrails (optional, recommended)

Quick Install

One command (downloads and installs everything):

bash <(curl -fsSL https://raw.githubusercontent.com/kastelldev/opus-guard/main/install.sh)

Or clone first and inspect (recommended):

We recommend reviewing the files before installing. The installer modifies your ~/.claude/settings.json and creates files in ~/.claude/agents/ and ~/.claude/hooks/. Everything is open — check exactly what will be installed.

git clone https://github.com/kastelldev/opus-guard.git
cd opus-guard
# Review the files — especially install.sh and hooks/agent-model-guard.js
# Then install:
bash install.sh

The installer never overwrites existing files — if you already have custom agent overrides, they are preserved. Your settings.json is backed up before any changes.

Then restart Claude Code.

What Gets Installed

~/.claude/
  agents/
    Explore.md          # Codebase exploration → Sonnet
    researcher.md       # Web research → Sonnet
    general-purpose.md  # Multi-step research → Sonnet (read-only)
    coder.md            # Code writing → Opus
  hooks/
    agent-model-guard.js  # PreToolUse enforcement hook
  settings.json           # 3 matchers added (safely merged)

Safe installation:

• Existing agents/hooks with the same name are skipped (never overwritten)
• settings.json is backed up before modification
• Only missing matchers are added (existing hooks preserved)
• Node.js required for settings.json merge

Uninstall

bash <(curl -fsSL https://raw.githubusercontent.com/kastelldev/opus-guard/main/uninstall.sh)

Removes all installed files and settings.json matchers. Restart Claude Code after.

Optional: CLAUDE.md Rules

Add to your CLAUDE.md or ~/.claude/CLAUDE.md for behavioral reinforcement:

## Subagent Delegation Rules

- **Web research** → `Agent(subagent_type: "researcher", model: "sonnet")`
- **Large codebase scan (5+ files)** → `Agent(subagent_type: "Explore", model: "sonnet")`
- **Simple reads (2-3 files)** → do directly, no subagent needed

How the Hook Works

The hook (agent-model-guard.js) enforces two rules:

1. WebSearch/WebFetch blocked in main Opus session — forces delegation to Sonnet subagent
2. Research agents must use model:sonnet — blocks spawning Explore/researcher/general-purpose without specifying Sonnet

Detection: data.agent_type field exists only in subagent context. Main session doesn't have it. This lets subagents and frameworks (GSD, custom workflows) work freely.

Bypass: export SKIP_RESEARCH_GUARD=1 in terminal before starting Claude Code.

Important: What Changes

• general-purpose becomes read-only. The built-in general-purpose agent can write files. Our override removes Write/Edit tools and moves code writing to a new coder agent. If your workflow relies on general-purpose writing files, Claude will automatically use coder instead — but be aware of this change.
• coder is a new agent. It doesn't exist in stock Claude Code. After installing, Claude uses it for code writing subagent tasks. It runs on Opus for quality.
• Opus users only. This optimization assumes you're running Opus as your main model. If you're on Sonnet, this tool has no effect (everything is already Sonnet).

Compatibility

• Windows: Uses process.stdin event-based reading (not /dev/stdin)
• macOS/Linux: Full support
• Claude Code: Requires hooks support (available in current versions)
• Node.js: Required for settings.json merge during install

How It Saves Tokens

Task	Without Guard	With Guard	Savings
Web search	47K (Opus)	17K (Sonnet)	2.7x
Codebase exploration	47K (Opus)	17K (Sonnet)	2.7x
Code writing	47K (Opus)	47K (Opus)	—

Research tasks are the majority of subagent work. Code writing stays on Opus for quality.

License

MIT