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. Make 30+ tool calls → Should see 150K warning
3. Request a new chat → Should get formatted handoff summary
4. Open multiple large files → Should see cumulative context estimate

Integration with .cursorrules

This skill should be referenced in .cursorrules after the "Prior Session Context" section (around line 106):

## MAX Mode Prevention & Context Monitoring

Monitor conversation context to avoid triggering MAX mode (200K token limit). See `.cursor/skills/context-monitor/SKILL.md` for full logic.

**Quick reference:**
- 🟡 100K tokens: Note internally
- 🟠 150K tokens: Warn user, suggest wrapping up
- 🔴 180K tokens: Recommend new chat with handoff summary

**High-cost files (auto-warn when opened):**
- Any file >5,000 lines (typically ~40-70K tokens)
- Any file >3,000 lines if other large files already in context
- Any agent transcript or log file

**When recommending new chat**, generate handoff summary with: task description, progress, next steps, @file references, critical context.

Why This Matters

• Cost control: MAX mode is expensive. Staying under 200K tokens saves money.
• Conversation efficiency: Handoff summaries preserve context without bloating the next chat.
• User experience: Proactive warnings let users decide when to break vs. AI forcing it.
• Strategic file loading: Knowing the cost of opening a file helps with decision-making.

This skill should be applied automatically throughout every conversation, not just when explicitly invoked.