model-matchmaker

Model Matchmaker

Stop paying Opus prices to rename files. Stop waiting 20 seconds for responses that should take 3.

A local hook for Cursor and Claude Code that classifies every prompt before it's sent and recommends the right model. Saves money (cloud APIs), speeds up your workflow (everyone), reduces resource usage (local models). No proxy, no API calls, no dependencies. Three files, two minutes to set up.

What It Does

Before each prompt is sent, Model Matchmaker reads what you're asking and which model you're on, then makes a call:

• Step-down: You're on Opus asking to git commit? Blocked. "Switch to Haiku, same result, 90% cheaper."
• Step-up: You're on Sonnet asking about architecture tradeoffs? Blocked. "Switch to Opus, you need the horsepower."
• Pass-through: You're on the right model? Prompt goes through instantly.

Override anytime by prefixing your prompt with !.

Auto-Switch (Optional)

Enable automatic model switching (v2+):

~/.cursor/hooks/toggle-auto-switch.sh on

When Model Matchmaker blocks a prompt, it now automatically switches the model and submits your message via keyboard automation:

1. Opens the model dropdown (Cmd+/)
2. Types the model name to search
3. Presses Enter 3 times (select model, confirm, submit message)
4. Terminal window flashes briefly, then closes
5. Your message is sent with the correct model (~3-4 seconds total)

Check status:

~/.cursor/hooks/toggle-auto-switch.sh status

Disable anytime with off. Uses macOS Accessibility permissions + Terminal.app proxy for safe, reliable switching.

Mode Support:
Auto-switch adapts to Cursor's different modes (Agent, Plan, Debug, Ask). In Plan mode, Haiku is unavailable, so Model Matchmaker automatically switches to Sonnet instead. To log your current mode:

~/.cursor/hooks/log-cursor-mode.sh plan   # When entering Plan mode
~/.cursor/hooks/log-cursor-mode.sh agent  # When back in Agent mode

This ensures correct dropdown navigation for each mode.

How It Works

flowchart TD
    SessionStart["Session starts"] --> InjectContext["sessionStart hook injects model guidance into system context"]
    UserSend["User hits Send"] --> ReadInput["beforeSubmitPrompt hook reads prompt + model"]
    ReadInput --> CheckOverride{"Prompt starts with '!'?"}
    CheckOverride -->|"Yes"| Allow["Allow immediately"]
    CheckOverride -->|"No"| Classify["Classify task via keyword matching"]
    Classify --> StepDown{"Overpaying? Opus/Sonnet for trivial task"}
    StepDown -->|"Yes"| Block["Block + recommend cheaper model"]
    StepDown -->|"No"| StepUp{"Underpowered? Sonnet/Haiku for complex task"}
    StepUp -->|"Yes"| Nudge["Block + recommend Opus"]
    StepUp -->|"No"| Allow

Three layers work together:

1. session-init.sh runs at session start and injects model-awareness context so the AI itself knows when to suggest switching
2. model-advisor.sh runs before every prompt, classifies the task, and blocks with a recommendation when you're on the wrong model
3. track-completion.sh runs when the agent loop ends, logging task outcomes for accuracy analysis

Quick Setup

# 1. Clone this repo (or just copy the files)
git clone https://github.com/coyvalyss1/model-matchmaker.git

# 2. Copy files to your Cursor config
cp model-matchmaker/hooks.json ~/.cursor/
mkdir -p ~/.cursor/hooks
cp model-matchmaker/hooks/*.sh ~/.cursor/hooks/

# 3. Make scripts executable
chmod +x ~/.cursor/hooks/*.sh

# 4. Restart Cursor (or Claude Code)

That's it. No packages, no build step, no config files to edit.

Enable Auto-Switch (Optional)

Model Matchmaker v2+ can automatically switch models when it blocks a prompt:

# Grant Accessibility permissions first
# System Settings > Privacy & Security > Accessibility > Add Terminal

# Then enable auto-switch
~/.cursor/hooks/toggle-auto-switch.sh on

# Check status
~/.cursor/hooks/toggle-auto-switch.sh status

# Disable anytime
~/.cursor/hooks/toggle-auto-switch.sh off

When enabled, the model switches and submits automatically (~3-4 seconds) instead of showing a block message.

Security: Auto-switch uses input whitelisting, rate limiting, atomic locking, frontmost verification, and scoped keyboard shortcuts to ensure it can only type one of three model names into Cursor's dropdown—nothing more. See SECURITY.md for full details.

Customization: The default whitelist includes haiku, sonnet, and opus. To use other models (GPT-4, Gemini, local models), edit ~/.cursor/hooks/auto-switch-model.sh lines 36-42:

case "$MODEL" in
    haiku|sonnet|opus|gpt-4|gemini)  # Add your models here
        ;;
    *)
        echo "[$(date -Iseconds)] SECURITY: Invalid model rejected: $MODEL" >> "$LOG_FILE"
        exit 1
        ;;
esac

Also update the classifier in model-advisor.sh to recommend your custom models.

What Gets Routed Where

Model	Task Type	Patterns
Haiku	Mechanical, simple	git commit, git push, rename, reorder, move file, delete file, add import, format, lint, prettier, eslint
Sonnet	Implementation	build, implement, create, fix, debug, add feature, write, component, service, page, deploy, test, refactor
Opus	Architecture, analysis	architect, evaluate, tradeoff, strategy, deep dive, redesign, across the codebase, multi-system, analyze, rethink

Opus is also recommended for prompts over 200 words or analytical questions over 100 words.

The classifier is conservative: it only blocks when confidence is high. A false allow (wasting some money) is always better than a false block (interrupting your flow with a wrong recommendation).

Analytics

Model Matchmaker tracks every recommendation, override, and task completion in structured NDJSON logs at ~/.cursor/hooks/model-matchmaker.ndjson.

What's Tracked

Event	Data Captured
Recommendation	Model used, recommendation, action (ALLOW/BLOCK/OVERRIDE), conversation ID, prompt snippet (40 chars)
Override	Same as recommendation, but action = OVERRIDE. Captures what was recommended vs. what you chose
Completion	Task outcome (completed/errored/aborted), model used, conversation ID

Conversation IDs link recommendations to outcomes, so you can measure whether overriding the advisor led to better or worse results.

View Your Stats

# Summary dashboard
./hooks/analytics.sh

# Last 7 days only
./hooks/analytics.sh --days 7

# JSON output (for scripting/dashboards)
./hooks/analytics.sh --json

Sample output:

==================================================
  MODEL MATCHMAKER ANALYTICS
  847 recommendations tracked
==================================================

  Actions:
       ALLOW:  512 (60.4%)
       BLOCK:  298 (35.2%)
    OVERRIDE:   37 ( 4.4%)

  Override rate: 4.4%
  Block rate:    35.2%

  Override breakdown (you disagreed):
    claude-4-sonnet (rec: opus): 22
    claude-4-opus (rec: haiku): 15

  Task Outcomes (312 conversations):
    Completed: 287
    Errored:   18
    Aborted:   7

  Override Outcomes:
    Completed after override: 33
    Errored after override:   4
==================================================

A high override rate with good completion outcomes means the classifier needs tuning for your workflow. A high override rate with errors means the advisor was probably right.

Four-Tier Data Strategy

Model Matchmaker gives you four levels of analytics, each with different privacy and sharing boundaries:

Tier 1: Automatic Local Logs (Default)

• Full NDJSON logs with all data: ~/.cursor/hooks/model-matchmaker.ndjson
• Includes: conversation IDs, prompt snippets (40 chars), model info, outcomes
• Privacy: Local only, never leaves your machine
• Use case: Your personal workflow analysis

Tier 2: Personal Optimization (skills/optimize-classifier/SKILL.md) ⭐ Recommended

• Analyzes your override patterns and auto-tunes your local classifier
• Finds keywords from prompts where you disagreed with the advisor
• Proposes changes to model-advisor.sh to match your preferences
• Privacy: Completely local, no data leaves your machine
• Use case: Make your classifier learn from your overrides
• Run this after 50+ prompts and a few overrides to tune it to your workflow

Tier 3: Personal Dashboard (analytics.sh)

• Aggregated stats from your logs: override rate, completion outcomes, patterns
• Run: ./hooks/analytics.sh or ./hooks/analytics.sh --days 7
• Privacy: Local only, no sharing
• Use case: Track your own accuracy, identify classifier gaps

Tier 4: Community Contribution (Optional, User-Reviewed)

• Sanitized report generated via Cursor skill: skills/share-analytics/SKILL.md
• AI-powered sanitization: removes project names, file paths, personal details
• Prompts → generic categories: "ui bug fix", "feature build", "API integration"
• Privacy: You review and approve before sharing
• Use case: Help improve the classifier for everyone
• Note: Not required for personal optimization (use Tier 2 instead)

The core workflow is: Use Model Matchmaker → Review dashboard → Optimize locally → (Optionally) contribute anonymized data.

Most users will only need Tiers 1-3. Tier 4 is if you want to help improve the community classifier.

Privacy

• Only the first 40 characters of each prompt are stored (for pattern analysis)
• All data stays local in ~/.cursor/hooks/model-matchmaker.ndjson
• No network calls, no telemetry, no cloud storage
• Delete the file anytime to clear your history

Override

Prefix any prompt with ! to bypass the advisor entirely:

! just do it on Opus, I know what I'm doing

The override is logged (so you can track accuracy) but the prompt goes through immediately with no blocking.

Skills

Model Matchmaker includes optional Cursor Agent skills that extend its functionality:

Context Monitor (skills/context-monitor/SKILL.md) 🆕

Problem: Cursor's MAX mode (Claude Opus 3.5, 200K token context) triggers automatically when context exceeds 200K tokens. Due to the larger context window, MAX mode requests can consume significantly more credits than typical requests.

Solution: Proactive context monitoring that warns before MAX mode triggers and helps you stay under the 200K limit.

How it works:

• 🟡 100K tokens: Notes internally, continues normally
• 🟠 150K tokens: Warns and suggests wrapping up or starting fresh chat
• 🔴 180K tokens: Recommends new chat immediately, offers handoff summary

Auto-triggers warnings when:

• Opening large files (>3,000 lines)
• Multiple large files in context (>5 files over 1,000 lines)
• Long conversations (>50 tool calls)
• Reading agent transcripts or logs

Key feature: Handoff Summaries

When recommending a new chat, the skill auto-generates a concise handoff summary:

• One-line task description
• Progress bullets (what's done)
• Next steps (numbered action items)
• @file references (what files need work)
• Critical context (1-2 sentences)

Example:

## Handoff Summary for New Chat

**Task**: Fix chat component short-response fallback bug

**Progress**:
- Identified root cause: validation guard blocking saves
- Removed guard from useChatManager.jsx
- Added fallback examples to API helper

**Next Steps**:
1. Test save flow with empty data
2. Verify data structure generation
3. Deploy to production

**Key Files**:
- @src/hooks/useChatManager.jsx — Removed guard
- @server/helpers/apiHelper.js — Added examples

**Context**: Short-response fallback was a symptom, not root cause.

Installation:

Copy the skill to your .cursor/skills/ directory: