feat: Add @handoff chat participant with health scoring algorithm (v0.2.0)

- Add @handoff chat participant with two commands:
  - @handoff analyze: Analyzes chat health with scoring algorithm
  - @handoff export: Triggers context export workflow

- Implement health scoring based on:
  - Message count (optimal: <20 messages)
  - Token usage estimation (if model supports countTokens())
  - Context degradation detection

- Redesign status bar:
  - Changed from session timer to persistent 'Check Chat Health' reminder
  - Click to open chat with @handoff analyze pre-filled

- Add new command: copilot-handoff.checkChatHealth

- Update documentation:
  - README.md: Document @handoff participant and health scoring
  - CHANGELOG.md: Add v0.2.0 with rationale for redesign
  - copilot-instructions.md: Fix TESTING.md path references
  - test suite: Add checkChatHealth command test

Breaking Changes:
- Status bar behavior changed from timer display to static reminder
- Architecture shifted from time-based tracking to health analysis

Rationale:
Time-based tracking proved ineffective for detecting actual chat
degradation. New approach uses evidence-based metrics (message count,
token usage) backed by research on 'Lost in the Middle' phenomenon.
Only monitors chats where @handoff is explicitly invoked.

Author: TSV Dev Environment

.github/AI_AGENT_SETUP_PROMPT_BACKUP.md

@@ -1,74 +1,180 @@
 # Copilot Instructions for copilot-handoff
 
 ## Project Overview
-This is a VS Code extension that tracks GitHub Copilot chat session duration and reminds developers to perform context-preserving handoffs when switching between Copilot agents or sessions.
+VS Code extension that tracks editor session duration and reminds developers to perform context-preserving handoffs. Helps prevent context degradation in long coding sessions by monitoring activity and providing structured context export.
 
-## Architecture (To Be Implemented)
+**Core Purpose**: Proxy-track general editor activity as a signal for Copilot usage, then notify users when session duration exceeds thresholds to encourage fresh context starts.
 
-### Core Components
-- **Session Tracker**: Monitors active Copilot chat sessions and tracks duration
-- **Notification System**: Alerts users when session approaches recommended handoff thresholds
-- **Context Preservation**: Helps users export/save conversation context before switching agents
-- **Settings Manager**: User-configurable thresholds and notification preferences
+## Architecture
 
-### VS Code Extension Structure
-Follow standard VS Code extension patterns:
-- `package.json`: Extension manifest with contribution points (commands, settings, activation events)
-- `src/extension.ts`: Entry point with `activate()` and `deactivate()` functions
-- Use VS Code Extension API for Copilot integration and UI notifications
+### Component Structure (4 main files in src/)
+- **extension.ts**: Coordinator - registers 4 commands, creates status bar, starts tracking/monitoring, handles 1-minute UI refresh
+- **sessionTracker.ts**: Activity monitor - listens to editor events (`onDidChangeTextDocument`, `onDidChangeActiveTextEditor`, `onDidChangeWindowState`), auto-resets after 5-min inactivity
+- **notificationManager.ts**: Notification scheduler - polls every 60 seconds, implements "once" vs "periodic" logic, persists notification state
+- **contextExporter.ts**: Markdown generator - builds structured handoff documents with workspace metadata, offers 3 export modes (clipboard/file/new doc)
 
-## Development Setup
+### Data Flow
+```
+Editor Event → SessionTracker.recordActivity() → updates lastActivityTime
+                                                ↓
+                                           globalState.set()
+                                                
+NotificationManager (60s poll) → reads duration → checks threshold → shows notification
+                                                                            ↓
+User clicks "Export Context" → ContextExporter.exportContext() → QuickPick → generates markdown
+```
+
+### State Persistence (globalState keys)
+All state lives in `ExtensionContext.globalState` (survives restarts, global across workspaces):
+- `sessionStartTime` - Session start timestamp
+- `lastActivityTime` - Last recorded activity (used for 5-min auto-reset)
+- `lastNotificationTime` - Last notification timestamp (for periodic intervals)
+- `hasShownInitialNotification` - Boolean flag for "once" mode
+
+**Critical Pattern**: Each component reads state in constructor, writes via private `saveState()` methods. No in-memory-only state.
+
+### Key Design Decisions
+- **Activity proxy tracking**: No direct Copilot Chat API exists, so tracks ANY editor activity (text changes, window focus, editor switches) as proxy for Copilot usage
+- **Polling architecture**: Uses `setInterval()` for status bar (60s) and notifications (60s) instead of reactive events - simpler but 1-minute granularity
+- **5-minute inactivity timeout**: If `Date.now() - lastActivityTime > 5min`, auto-resets session to prevent stale tracking after breaks
+- **Global state scope**: Extension state is per VS Code instance, NOT per workspace (sessionStartTime shared across all folders)
+
+## Development Workflow
+
+### Build & Debug
+```bash
+npm install              # Install deps (requires Node 20+)
+npm run compile         # TypeScript → out/ (one-time build)
+npm run watch           # Watch mode (rebuilds on save)
+F5                      # Launch Extension Development Host in new VS Code window
+```
+
+**F5 Debugging Setup**: VS Code auto-creates `Extension Host` debug config. Set breakpoints in TypeScript source (sourcemaps enabled). Check Debug Console for `console.log()` output from extension.
+
+### Testing
+```bash
+npm test                # Runs: compile + lint + launches test instance
+```
 
-### Prerequisites
-- Node.js (LTS version recommended)
-- VS Code with Extension Development Host capabilities
-- TypeScript for type safety
+**Test Structure**: Integration tests in `src/test/suite/extension.test.ts` using Mocha + `@vscode/test-electron`. Tests verify:
+- Extension activation (`vscode.extensions.getExtension()`)
+- Command registration (`vscode.commands.getCommands()`)
+- Config defaults (`vscode.workspace.getConfiguration()`)
 
-### Key Commands (To Be Defined)
-- `npm install`: Install dependencies
-- `npm run compile`: Build TypeScript
-- `npm run watch`: Rebuild on changes
-- `F5` in VS Code: Launch Extension Development Host for testing
+**Manual Testing Required**: Chat participant features (@handoff) need manual verification. See [TESTING.md](../TESTING.md) for checklist.
 
-## VS Code Extension Best Practices
+### Linting & Packaging
+```bash
+npm run lint            # ESLint with TypeScript parser (@typescript-eslint)
+npm run package         # Creates .vsix (requires Node 20+)
+```
+
+**Note**: `package` and `publish` scripts require Node 20+ and use `node node_modules/@vscode/vsce/vsce` to avoid global install.
 
-### Activation Events
-- Use `onStartupFinished` or Copilot-specific activation events to minimize startup impact
-- Consider `onLanguage`, `onCommand`, or custom activation events based on when tracking should begin
+## Configuration (package.json contributes.configuration)
 
-### Copilot Integration
-- Monitor VS Code's Chat API for active sessions
-- Use `vscode.chat` namespace APIs when available
-- Track chat panel focus/blur events to determine active session duration
+All settings under `copilot-handoff.*` namespace with validation:
+- `sessionThresholdMinutes` (5-180, default 30) - When to show first reminder
+- `notificationFrequency` ("once" | "periodic" | "never", default "periodic") - Reminder behavior
+- `periodicReminderMinutes` (1-60, default 10) - Interval for periodic mode
+- `autoExportContext` (boolean, default false) - **Not implemented** - reserved for future auto-export
+- `showStatusBar` (boolean, default true) - Show/hide clock icon in status bar
+- `trackingEnabled` (boolean, default true) - Master toggle for all tracking
 
-### User Experience
-- Show status bar item with session duration
-- Use non-intrusive notifications (information messages, not warnings)
-- Allow users to dismiss or snooze handoff reminders
-- Persist session state across VS Code window reloads
+**Reading Config**: Always use `vscode.workspace.getConfiguration('copilot-handoff').get<Type>('key', defaultValue)` with explicit defaults for type safety.
 
-## Configuration
+## Project-Specific Patterns
 
-### Expected Settings (in `package.json` contributions)
+### Command Registration (4 commands)
+All follow `copilot-handoff.<action>` naming in `extension.ts activate()`:
+```typescript
+vscode.commands.registerCommand('copilot-handoff.showSessionInfo', () => {...})
+```
+Always push to `context.subscriptions` for cleanup. Commands:
+- `showSessionInfo` - Modal with duration, threshold, action buttons
+- `exportContext` - Async QuickPick → 3 export options
+- `resetSession` - Calls `sessionTracker.resetSession()`, shows info message
+- `toggleTracking` - Flips `trackingEnabled` config value
+
+### Event Listeners (sessionTracker.ts)
+Activity tracking via 4 event types in `startTracking()`:
 ```typescript
-"copilot-handoff.sessionThresholdMinutes": number    // When to remind (default: 30)
-"copilot-handoff.notificationFrequency": string      // "once" | "periodic" | "never"
-"copilot-handoff.autoExportContext": boolean         // Auto-save context on handoff
+vscode.workspace.onDidChangeTextDocument(() => this.recordActivity())
+vscode.window.onDidChangeActiveTextEditor(() => this.recordActivity())
+vscode.window.onDidChangeWindowState(state => {...})
+vscode.commands.registerCommand('workbench.panel.chat.view.copilot.focus', ...)
 ```
+All listeners pushed to `this.listeners[]` array, disposed in `dispose()`.
 
-## Testing Strategy
-- Unit tests for session tracking logic
-- Integration tests using VS Code Extension Test Runner
-- Manual testing in Extension Development Host
-- Test with real Copilot chat sessions for accurate duration tracking
-
-## Project Conventions
-- Use TypeScript strict mode for type safety
-- Follow VS Code extension naming conventions for commands (`copilot-handoff.commandName`)
-- Store minimal state; prefer VS Code's built-in storage APIs (globalState/workspaceState)
-- MIT License - keep copyright notice in new files
-
-## Known Constraints
-- Extension depends on GitHub Copilot being installed and active
-- Chat API availability may vary by VS Code version
-- Session tracking should not impact performance or interrupt workflows
+### Status Bar Pattern
+**Non-reactive updates**: Uses `setInterval()` instead of listening to state changes:
+```typescript
+setInterval(() => updateStatusBar(), 60000)  // Every minute
+```
+Format: `$(clock) Xh Ym` or `$(clock) Ym`, tooltip shows "Click for details". Hide if `trackingEnabled=false` or `showStatusBar=false`.
+
+### Context Export Template Structure
+`ContextExporter.generateContextSummary()` builds markdown with:
+1. Metadata block: timestamp, workspace name, current file
+2. Auto-detected context: active selection, language, open editors
+3. Manual fill-in sections: "What I Was Working On", "Key Decisions Made", "Next Steps"
+
+**Export modes**:
+- Clipboard: Direct `vscode.env.clipboard.writeText()`
+- Save to File: `vscode.window.showSaveDialog()` → `fs.writeFileSync()`
+- New Document: `vscode.workspace.openTextDocument({ content, language: 'markdown' })`
+
+## TypeScript Configuration (tsconfig.json)
+
+- **Target**: ES2020 (supports Node.js 20+ features like optional chaining)
+- **Module**: CommonJS (VS Code extension requirement)
+- **Strict mode**: Enabled (null checks, strict function types, no implicit any)
+- **Output**: `out/` directory (gitignored, created on compile)
+- **Exclude**: `node_modules`, `.vscode-test`, `src/test` (tests run via separate test runner)
+
+**Source maps enabled**: Set breakpoints in `.ts` files, not compiled `.js`.
+
+## Known Limitations & Future Work
+
+- **No direct Copilot Chat API**: Tracks general editor activity as proxy (may trigger when not using Copilot)
+- **Global state scope**: Session state shared across all workspace folders (not workspace-specific)
+- **Notification granularity**: 1-minute polling intervals (not real-time)
+- **Auto-export placeholder**: `autoExportContext` setting exists but feature not implemented
+- **Manual handoff required**: No automated context export or Copilot Chat integration
+
+## Extending the Extension
+
+### Adding a New Command
+1. Add to `package.json` → `contributes.commands` with `command` and `title`
+2. Register in `extension.ts` `activate()`:
+   ```typescript
+   context.subscriptions.push(
+       vscode.commands.registerCommand('copilot-handoff.myCommand', async () => {...})
+   )
+   ```
+3. Update README.md command list and quickstart guide
+
+### Adding a New Configuration
+1. Add to `package.json` → `contributes.configuration.properties` with `type`, `default`, `description`, optional `enum`/`minimum`/`maximum`
+2. Read in code:
+   ```typescript
+   const config = vscode.workspace.getConfiguration('copilot-handoff');
+   const value = config.get<Type>('myKey', defaultValue);
+   ```
+3. For reactive behavior: Listen to `vscode.workspace.onDidChangeConfiguration(e => { if (e.affectsConfiguration('copilot-handoff.myKey')) {...} })`
+
+### Modifying Session Tracking Logic
+Edit `SessionTracker.startTracking()` to add/remove event listeners. Common patterns:
+- Add listener: `this.listeners.push(vscode.workspace.onXxx(() => this.recordActivity()))`
+- Change inactivity timeout: Modify `ACTIVITY_TIMEOUT` constant (currently 5 * 60 * 1000 ms)
+- Custom activity logic: Override `recordActivity()` with conditional checks before `this.lastActivityTime = Date.now()`
+
+### Testing Notification Timing
+For manual testing, temporarily reduce thresholds:
+```json
+{
+  "copilot-handoff.sessionThresholdMinutes": 1,
+  "copilot-handoff.periodicReminderMinutes": 1
+}
+```
+Wait 1-2 minutes to trigger notifications. See [TESTING.md](../TESTING.md) for full checklist.

.github/copilot-instructions.md

@@ -70,6 +70,9 @@ web_modules/
 .env.*
 !.env.example
 
+# Personal Access Token for marketplace publishing
+.vsce-pat
+
 # parcel-bundler cache (https://parceljs.org/)
 .cache
 .parcel-cache

.gitignore

@@ -8,3 +8,4 @@ src/**
 tsconfig.json
 node_modules/**
 .github/**
+.vsce-pat

.vscodeignore

@@ -2,6 +2,40 @@
 
 All notable changes to the "Copilot Handoff" extension will be documented in this file.
 
+## [0.2.0] - 2026-01-27
+
+### Added
+- **@handoff Chat Participant**: New chat participant for analyzing chat health directly in Copilot Chat
+  - `@handoff analyze` - Analyzes current chat context quality with health scoring
+  - `@handoff export` - Triggers context export workflow
+- **Health Scoring Algorithm**: Intelligent analysis of chat quality based on:
+  - Message count (optimal: <20 messages)
+  - Token usage estimation (if model supports `countTokens()`)
+  - Context degradation detection
+- **Persistent Status Bar Reminder**: Status bar now shows "Check Chat Health" button instead of timer
+  - Click to open chat with `@handoff analyze` pre-filled
+  - Always visible reminder to check chat quality
+- **New Command**: `Copilot Handoff: Check Chat Health` for quick access
+
+### Changed
+- **Status Bar Behavior**: Changed from displaying session duration to showing persistent "Check Chat Health" reminder
+- **Architecture**: Redesigned from time-based tracking to chat health analysis
+- **User Experience**: Shifted from passive timer to active health monitoring when @handoff is invoked
+
+### Technical
+- Added chat participant registration in extension.ts
+- Implemented `analyzeChatHealth()` function with scoring algorithm
+- Added `handleChatRequest()` to process @handoff commands
+- Modified status bar to show static reminder instead of dynamic timer
+- Updated package.json with chatParticipants contribution
+
+### Rationale
+Time-based tracking proved ineffective for detecting actual chat degradation. The new approach:
+- Uses evidence-based metrics (message count, token usage) backed by research on "Lost in the Middle" phenomenon
+- Provides on-demand analysis rather than arbitrary time thresholds
+- Gives users actionable health scores and recommendations
+- Only monitors chats where @handoff is explicitly invoked (respects user privacy)
+
 ## [0.1.0] - 2026-01-26
 
 ### Initial Release
@@ -33,3 +67,4 @@ All notable changes to the "Copilot Handoff" extension will be documented in thi
 - 5-minute inactivity timeout for automatic session resets
 - Non-intrusive notification system
 - Lightweight background processing
+

CHANGELOG.md

@@ -182,22 +182,23 @@ code --install-extension copilot-handoff-*.vsix
 
 1. **Install the extension** (see above)
 2. **Reload VS Code** if prompted
-3. **Look for the clock icon** ⏰ in the status bar (bottom-right)
-4. **Click the icon** to see your current session info
+3. **Look for the $(pulse) Check Chat Health button** in the status bar (bottom-right)
+4. **Click the button** or type `@handoff analyze` in Copilot Chat to check chat health
 
-That's it! The extension is now tracking your session.
+That's it! The extension is ready to analyze your Copilot chats.
 
-### Your First Handoff
+### Your First Health Check
 
-1. Work for 30+ minutes (or your configured threshold)
-2. See a notification: *"Copilot session has been active for 30m..."*
-3. Click **"Export Context"**
-4. Choose your preferred format:
-   - 📋 **Copy to Clipboard** - Quick summary
-   - 💾 **Save to File** - Full markdown document
-   - 📝 **Create Handoff Document** - Structured template
-5. Fill in the template sections if using handoff document
-6. Click **"Reset Session"** to start fresh
+1. Open Copilot Chat and start a conversation with Copilot
+2. After several exchanges, click the **$(pulse) Check Chat Health** button in status bar
+3. Chat opens with `@handoff analyze` pre-filled
+4. Press **Enter** to see your chat health report with:
+   - Overall health score (0-100)
+   - Message count and token usage
+   - Issues detected (if any)
+   - Recommendations
+5. If score is below 70, click **Export Context for Handoff** button
+6. Start a fresh chat with exported context as reference
 
 ---
 
@@ -209,18 +210,34 @@ Access all features via the **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`)
 
 | Command | Description | When to Use |
 |---------|-------------|-------------|
+| `Copilot Handoff: Check Chat Health` | Open chat with @handoff analyze pre-filled | Quick access to health analysis |
 | `Copilot Handoff: Show Session Info` | View detailed session information | Check current session status anytime |
 | `Copilot Handoff: Export Chat Context` | Export context with format options | Before breaks, context switches, or handoffs |
 | `Copilot Handoff: Reset Session Timer` | Manually reset the timer | After a handoff or when starting fresh work |
 | `Copilot Handoff: Toggle Tracking` | Enable/disable session tracking | Temporarily pause tracking |
 
 ### Status Bar
 
-The status bar item shows:
-- ⏰ **Icon** indicating active tracking
-- **Duration** in minutes or hours (e.g., `25m` or `1h 15m`)
-- **Click** to view session details
-- **Hover** for quick info tooltip
+The status bar item provides quick access to chat health analysis:
+- $(pulse) **"Check Chat Health"** button always visible
+- **Click** to open Copilot Chat with `@handoff analyze` pre-filled
+- **Press Enter** to analyze your current chat's context quality
+- **Hover** for quick tooltip explaining functionality
+
+### @handoff Chat Participant
+
+Use the `@handoff` participant directly in Copilot Chat:
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `@handoff analyze` | Analyze current chat health with scoring | Check if chat context is degrading |
+| `@handoff export` | Export context for handoff | Before starting a fresh chat session |
+
+**Health Scoring:** Analyzes message count, token usage (if available), and context quality. Shows:
+- **Excellent (90-100)**: Chat is healthy, continue working
+- **Good (70-89)**: Chat is fine, monitor for quality issues
+- **Fair (50-69)**: Consider a handoff soon
+- **Poor (<50)**: Immediate handoff recommended - context degradation likely affecting quality
 
 ---