/context-monitor

name: context-monitor
description: Monitor conversation context and prevent MAX mode by warning at token thresholds and generating handoff summaries. Use when context approaches 100K/150K/180K tokens or when working with high-cost files.

MAX Mode Prevention & Context Monitoring

The Problem

Cursor's MAX mode (Claude Opus 3.5, 200K token context) is expensive and should be reserved for truly complex tasks. Context can balloon quickly when:

• Opening large files (e.g., a 9,378-line React component)
• Loading chat transcripts or logs (1-10MB)
• Accumulating tool calls and responses across long sessions
• Reading multiple files speculatively

**Once context exceeds 200K tokens, the conversation is forced into a new chat with a handoff summary.** This wastes user time and disrupts flow.

The Solution

**Monitor context throughout the conversation (not just at start).** Warn at thresholds and proactively recommend starting a new chat with a clean handoff.

Token Thresholds

🟡 Yellow Alert (100K tokens)

**Action**: Note the context size internally. No user warning yet.

🟠 Orange Alert (150K tokens)

**Action**: Warn the user and suggest wrapping up current work or starting a new chat if the task is open-ended.

**Warning format:**

⚠️ Context approaching 150K tokens. Consider starting a new chat after this task to avoid MAX mode. I can generate a handoff summary.

🔴 Red Alert (180K tokens)

**Action**: Strongly recommend starting a new chat. Offer to generate a handoff summary immediately.

**Warning format:**

🚨 Context at 180K tokens (MAX mode limit: 200K). Recommend starting a new chat now. I can generate a handoff summary with:
- Task description
- Progress so far
- Next steps
- @file references

Automatic Triggers

Issue a warning automatically when:

1. **Large file opened** (>3,000 lines):

• Example: DashboardPage.jsx (9,378 lines) = ~70K tokens
• Example: useChatManager.jsx (4,178 lines) = ~30K tokens
• Any file >5,000 lines = likely >40K tokens

2. **Multiple large files in context** (>5 files over 1,000 lines each)

3. **Long conversation** (>50 tool calls in current chat)

4. **Transcript search** (reading agent-transcripts/*.txt files)

5. **Plan file creation** (plans are meta-work that inflate context)

High-Cost Files (Known)

Track your project's largest files and add them to your monitoring list. Common examples:

• Main dashboard/app components (5,000-10,000 lines)
• Complex state management hooks (3,000-5,000 lines)
• Generated files (API clients, schema definitions)
• Any `.log` file
• Any agent transcript (`.txt` files in agent-transcripts/)

**When opening these files**, immediately note context cost and warn if already over 100K.

**To find your largest files:**

find . -name "*.jsx" -o -name "*.tsx" -o -name "*.js" -o -name "*.ts" | \
  xargs wc -l | sort -rn | head -20

Handoff Summary Format

When recommending a new chat, generate a concise handoff summary using this template:

## Handoff Summary for New Chat

**Task**: [One-line description]

**Progress**:
- [Bullet point 1]
- [Bullet point 2]
- [Bullet point 3]

**Next Steps**:
1. [Action item 1]
2. [Action item 2]
3. [Action item 3]

**Key Files**:
- @path/to/file1.jsx — [what was changed/what needs work]
- @path/to/file2.js — [what was changed/what needs work]

**Context**: [1-2 sentences of critical context that must be preserved]

**Handoff example:**

## Handoff Summary for New Chat

**Task**: Fix chat component falling back to short responses when user profile is empty

**Progress**:
- Identified root cause: validation guard blocking all saves when user data incomplete
- Removed guard from useChatManager.jsx (lines 2847-2863)
- Added fallback examples to API helper function

**Next Steps**:
1. Test save flow with empty profile
2. Verify data structure generation on first save
3. Deploy to production if test passes

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

**Context**: The short-response fallback was a symptom, not the root cause. Real issue was validation logic preventing data generation.

Implementation Guide

For Cursor AI

At the start of each response: 1. **Check conversation length** (tool call count, file read count) 2. **Check if large files are in context** (match against known high-cost files list) 3. **Estimate current token count** (rough heuristic: 50 tool calls = ~100K tokens; one 9K line file = ~70K tokens) 4. **Issue warning if threshold crossed**

Mid-Conversation Monitoring

After opening a large file:

📊 Context note: DashboardPage.jsx added (~70K tokens). Current context estimate: ~120K tokens.

After 30+ tool calls:

⚠️ Context approaching 150K tokens (30+ tool calls). Consider wrapping up or starting fresh chat.

Handoff Trigger Phrases

When the user says:

• "This is taking forever"
• "Start a new chat"
• "Can we move to a new conversation?"
• "Feels like we're dragging"
• "MAX mode is too expensive"

**Immediately generate a handoff summary** without asking.

Cost Comparison

**Typical scenario without monitoring:**

• Start chat: 20K tokens
• Open DashboardPage.jsx: +70K = 90K
• Open useChatManager.jsx: +30K = 120K
• 20 tool calls: +40K = 160K
• Read logs/transcripts: +30K = 190K
• **Triggers MAX mode** (expensive, could have been avoided)

**With monitoring:**

• Warning at 150K → user starts new chat
• New chat: 20K tokens
• Continue work efficiently
• **Savings: 170K tokens** (stays under 200K limit)

When NOT to Warn

Don't warn if:

• The task is nearly complete (1-2 steps remaining)
• The user explicitly said "use MAX mode" or "I don't care about cost"
• The conversation is already at the final deployment/verification stage

Testing the Skill

To verify this skill is working:

1. **Open a large file (>5,000 lines)** → Should see context note 2. **Ma