AI Context Handoff Guard

A local, provider-neutral VS Code extension that gives a real-time context risk warning when an AI chat session is likely becoming token-heavy. Works with GitHub Copilot, Claude Code, Continue, Codeium, Windsurf, Kilo Code, Cline, Cursor, and other AI agents inside VS Code-compatible editors — including native Cursor and Windsurf IDE builds.

What this extension is: A local heuristic that warns when long AI-assisted coding sessions are likely becoming context-heavy.

What this extension is not: A detector of actual AI token usage. The VS Code API does not expose model context windows, token counts, or chat transcripts from any AI provider.

What It Does

• Monitors your editor session for signs of high AI chat context risk using local signals only — session duration and editor activity counts.
• Shows a native VS Code modal warning when estimated pressure reaches your configured threshold.
• Detects which AI agent extensions — and native AI IDE builds such as Cursor and Windsurf — are active.
• Shows a status bar indicator with a live numeric score you can click to open the Quick Actions menu: Copy Handoff Draft, Toggle AI Mode, Explain Score, Mark New Chat Started, and more.
• Offers a Copy Handoff Draft action that copies a structured Markdown template to your clipboard — fill it in and paste into a fresh chat.
• Can reset the context pressure meter without touching any AI provider or chat history.
• Runs automatically when VS Code starts and stops when VS Code closes. No background daemon. No separate process.
• No model calls, no AI provider API calls, no network requests. Nothing leaves your machine.

Supported AI Agents

The extension detects the following AI agent extensions when they are installed in the same VS Code-compatible editor:

Detection is read-only — no data is read from these extensions. Related IDs are grouped into a single family label (e.g. both Copilot extension IDs appear as "Copilot"). Detection affects the warning and summary text only; it does not change the pressure score.

Native IDE detection: If the editor's app name is "Cursor" or "Windsurf", those families are automatically added to detected agents even without an extension ID match — because those IDEs bake AI into their core binary rather than installing it as an extension.

To add an agent not in the list above, use the aiContextGuard.extraAgentExtensionIds setting.

Compatible Editors

First-class: Microsoft VS Code.

Supported after validation: VS Code Insiders, VSCodium, Gitpod, native Cursor, native Windsurf, and other editors based on the VS Code extension API that support VSIX installation and the onStartupFinished activation event.

Not supported by this extension: JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.) — these require a separate JetBrains plugin.

How It Works

Pressure is estimated from two local signals combined into a raw score 0–100, then adjusted by two real-time multipliers before display.

Note: The extension cannot read model context windows, token counts, or chat transcripts from any AI provider. All agents — Copilot, Claude, Continue, Cline, Codex-style, Windsurf, Cursor, and others — are metered by the same local heuristic. The warning is a context-risk indicator, not a precise token measurement.

Multipliers applied after the raw score:

Final score = raw × idle decay × AI-likelihood. The numeric value shown in the status bar is the final adjusted score.

Activity counters capture event counts only — no file names, no content, no workspace names, no paths.

All three activity types use a burst model: rapid events count as at most one credit per configurable time window, preventing rapid tool-use or typing from inflating the score.

The warning popup fires when the final score reaches strongThreshold (default: 75) and an AI agent is detected (or warnWithoutDetectedAgent is enabled). A cooldown (default: 45 min) prevents notification spam.

Known accuracy limits

These are expected trade-offs of a provider-neutral, privacy-first tool. Use the score as an early-warning signal, not an exact measurement.

Warning Buttons

The warning popup has five actions:

After Copy Handoff Draft, the extension applies the afterCopyAction setting (default: apply cooldown) so the warning does not immediately reappear.

The extension does not read chat transcripts, call a model, or open a new chat automatically. The handoff draft is built from safe local metadata only.

Handoff Draft Template

When you copy a handoff draft, you get a structured Markdown template with sections to fill before pasting into your next chat:

• Current Objective — what you are trying to achieve right now
• What Is Working — confirmed working parts
• What Changed — what you discovered or changed in the last session
• Blockers / Risks — current problems or uncertainties
• Next Best Step — the first concrete action for the new chat
• Context To Ignore — old details or dead ends to exclude
• Session Metadata — auto-generated: score, session time, detected agents (no file names, no content, no paths)

Settings

All settings are application-scoped (apply across all workspaces for the current editor profile).

Quick test

To verify the extension works immediately after install:

1. Confirm you have at least one supported AI agent installed (e.g. GitHub Copilot). If no agent is detected, warnings are suppressed by default — toggle AI mode to Using AI first to bypass that check.
2. Set aiContextGuard.strongThreshold to 20 and aiContextGuard.timeThresholdMinutes to 5 in settings.
3. Wait about 2 minutes (checks run every 60 seconds). The status bar score should rise and a warning popup should appear.
4. Click Copy Handoff Draft — confirm the clipboard contains the structured Markdown template. The warning should not immediately reappear.
5. Reset both settings to their defaults.

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for:

Privacy and Security

• No data leaves the machine. No network calls, no telemetry at all, no model calls.
• No content is read. Activity signals are counts only — no file names, no prompts, no responses, no workspace names, no paths in UI or logs.
• No personal paths in UI or notifications. Warnings and status show only numeric scores, elapsed time, agent counts, and activity event counts.
• No provider storage reads. The extension does not read AI provider databases, chat transcripts, prompts, or responses.
• Enterprise policy. Enterprise administrators can disable aiContextGuard.enabled at the application level to prevent all activity.
• Command surface. Like all VS Code extensions, this extension's commands (e.g. reset meter, copy handoff draft) can be invoked programmatically by other installed extensions — this is the standard VS Code trust model. The copy command is rate-limited to once per 5 seconds to prevent clipboard-overwrite abuse, and suppression settings are capped at 24 hours so the guard cannot be silenced indefinitely.

Installation

Visual Studio Marketplace

Search for AI Context Handoff Guard in the VS Code Extensions view or install from the Marketplace web page.

Open VSX

For VSCodium and other Open VSX-compatible editors, install from open-vsx.org.

Manual VSIX install (enterprise / offline)

code --install-extension ai-context-handoff-guard.vsix

Reload VS Code after installation. The extension activates automatically on next startup.

Limitations

• Exact token counts are not available. Pressure is estimated from local heuristics — session time, edit bursts, nav bursts, terminal bursts. The VS Code API does not expose model context windows or token usage from any AI provider.
• False positives are possible. A long coding session without AI chat use will still accumulate a high score. Use Not Using AI or Mark New Chat Started to suppress or reset it.
• No-agent passive mode. When no known AI extension is detected, modal warnings are suppressed by default (warnWithoutDetectedAgent: false). The AI-likelihood factor also reduces the score to ≈35% of raw, so the default threshold of 75 is unlikely to be crossed without a detected agent. You can enable warnings without a detected agent via the setting, but you may also need to lower strongThreshold below 35.
• False negatives are possible. Pasting very large content directly into an AI chat within a short session will not trigger the warning because activity counts remain low. The extension cannot read chat content.
• Session tracking resets when VS Code restarts. The extension does not persist state across VS Code sessions.
• Agent detection maintenance. Extension IDs change over time as tools rename, fork, or deprecate. The extraAgentExtensionIds setting lets you add unlisted agents. Native Cursor and Windsurf are detected via app name, not extension ID.
• No runtime dependency. The extension is pure JavaScript; no Python, Node scripts, or external processes are required.