🤝 Copilot Handoff

Track GitHub Copilot chat session duration and get timely reminders for context-preserving handoffs

Features • Installation • Usage • Configuration • Contributing • Roadmap

📖 Table of Contents

• Why Copilot Handoff?
• Key Features
• Demo
• Installation
• Quick Start
• Detailed Usage
• Configuration
• Use Cases
• Why Context Handoffs Matter
• Requirements
• FAQs
• Contributing
• Support
• License

🌟 Why Copilot Handoff?

Core Benefits

✨ Key Features

🎯 Session Tracking

The extension automatically monitors your Copilot usage and tracks session duration with:

• Real-time status bar display
• Persistent state across VS Code restarts
• Intelligent inactivity detection (auto-resets after 5 minutes of inactivity)

📢 Smart Notifications

Get notified when your session exceeds the configured threshold:

• Once mode: Single reminder per session
• Periodic mode: Regular reminders at customizable intervals
• Never mode: Tracking without notifications

📝 Context Preservation

When it's time for a handoff, export your context in multiple ways:

• Copy to Clipboard: Quick context summary
• Save to File: Markdown document with full details
• Handoff Template: Structured document with sections for tasks, decisions, and next steps

🎬 Demo

Coming Soon: Video demonstration showing the complete workflow

How It Works

graph LR
    A[Start Coding] --> B[Session Tracking Begins]
    B --> C{Threshold Reached?}
    C -->|No| B
    C -->|Yes| D[Show Notification]
    D --> E{User Action}
    E -->|Export Context| F[Save Handoff Document]
    E -->|Reset Timer| B
    E -->|Remind Later| G[Snooze Notification]
    G --> B
    F --> H[Continue Fresh Session]

Typical Workflow

1. 🚀 Start Working - Extension automatically begins tracking
2. ⏱️ Time Passes - Duration shown in status bar
3. 🔔 Get Notified - Reminder appears at your threshold (default: 30 min)
4. 📋 Export Context - Save your work, decisions, and next steps
5. 🔄 Start Fresh - Begin a new session with clear context

📦 Installation

From VS Code Marketplace (Recommended)

1. Open Extensions view in VS Code (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for "Copilot Handoff"
3. Click Install

From Command Palette

1. Press Ctrl+P / Cmd+P
2. Type: ext install curtisfranks.copilot-handoff
3. Press Enter

Manual Installation

Download the .vsix file from Releases and install via:

code --install-extension copilot-handoff-*.vsix

🚀 Quick Start

First Time Setup

1. Install the extension (see above)
2. Reload VS Code if prompted
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 ready to analyze your Copilot chats.

Your First Health Check

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

📚 Detailed Usage

Commands

Access all features via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Status Bar

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:

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

⚙️ Configuration

⚙️ Configuration

Customize every aspect in VS Code Settings (Ctrl+, / Cmd+,). Search for copilot-handoff:

All Settings

Configuration Examples

Conservative (Less Interruption)

{
  "copilot-handoff.sessionThresholdMinutes": 60,  // 1 hour
  "copilot-handoff.notificationFrequency": "once",
  "copilot-handoff.showStatusBar": true
}

Aggressive (Frequent Handoffs)

{
  "copilot-handoff.sessionThresholdMinutes": 15,  // 15 minutes
  "copilot-handoff.notificationFrequency": "periodic",
  "copilot-handoff.periodicReminderMinutes": 5
}

Silent Mode (Tracking Only)

{
  "copilot-handoff.notificationFrequency": "never",
  "copilot-handoff.showStatusBar": true  // Still see status
}

🎯 Use Cases

Individual Developers

Long Coding Sessions

• Get reminded to take breaks
• Preserve context before switching tasks
• Document decisions during extended sessions

Context Switching

• Export context when moving between projects
• Save state before meetings or interruptions
• Resume work with clear notes

Team Collaboration

Pair Programming Handoffs

• Export session context for partner
• Document decisions made during pairing
• Preserve context across shifts

Code Reviews

• Export chat context for PR description
• Share AI-assisted insights with team
• Document rationale for changes

Learning & Documentation

Tutorial Creation

• Export conversation as learning material
• Document problem-solving approaches
• Create step-by-step guides from sessions

Knowledge Preservation

• Save important AI responses
• Build personal knowledge base
• Create reference documentation

💡 Why Context Handoffs Matter

The Science Behind It

Research shows that AI chat models perform best with focused, time-limited conversations:

Note: These are approximate values based on general AI behavior patterns

Benefits of Regular Handoffs

📋 Requirements

❓ Frequently Asked Questions

🐛 Known Issues

See all open issues and report new ones!

📝 Release Notes

Version 0.1.0 (Current)

Initial Release - January 26, 2026

✨ Features

• Session duration tracking with persistent state
• Smart notification system (once/periodic/never modes)
• Context export with 3 formats (clipboard/file/template)
• Status bar integration with real-time updates
• Comprehensive configuration system
• 5-minute inactivity auto-reset

🔧 Technical

• TypeScript with strict mode
• Full VS Code Extension API compliance
• Zero dependencies for users
• Cross-platform support

See CHANGELOG.md for complete history.

"copilot-handoff.sessionThresholdMinutes": 30,

// How often to show reminders: "once", "periodic", or "never" "copilot-handoff.notificationFrequency": "periodic",

// Minutes between periodic reminders "copilot-handoff.periodicReminderMinutes": 10,

// Automatically export context when handoff is triggered "copilot-handoff.autoExportContext": false,

// Show session duration in status bar "copilot-handoff.showStatusBar": true,

// Enable session tracking "copilot-handoff.trackingEnabled": true }

## Context Export Format

The handoff template includes:

- **Session metadata**: Timestamp, workspace, current file
- **Working state**: Active files, selections, language
- **Guided sections**:
  - What I was working on
  - Key decisions made
  - Next steps
  - Important context notes

## Best Practices

1. **Set realistic thresholds**: Default is 30 minutes, adjust based on your workflow
2. **Use periodic reminders**: Keep context fresh with regular check-ins
3. **Export before breaks**: Save context before stepping away
4. **Document decisions**: Use the handoff template to capture important choices
5. **Reset after handoffs**: Start fresh after exporting and switching contexts

## 💡 Why Context Handoffs Matter

AI chat sessions can accumulate context that becomes less relevant over time. Regular handoffs help:

- ✅ Maintain AI response quality
- ✅ Preserve important decisions and context
- ✅ Create natural breakpoints in your workflow
- ✅ Improve collaboration when working in teams
- ✅ Better organize your development sessions

---

## 📋 Requirements

- Visual Studio Code 1.85.0 or higher
- GitHub Copilot extension (recommended, but not required)

---

## 🐛 Known Issues

- Session tracking monitors general editor activity as a proxy for Copilot usage
- Direct Copilot Chat API events may not be fully accessible in all VS Code versions

See the [issues page](https://github.com/chf3198/copilot-handoff/issues) to report problems or suggest features.

---

## 📝 Release Notes

### 0.1.0 - Initial Release

- Session tracking with configurable thresholds
- Smart notification system
- Context export with multiple formats
- Status bar integration
- Comprehensive configuration options

See [CHANGELOG.md](https://github.com/chf3198/copilot-handoff/blob/HEAD/CHANGELOG.md) for full release history.

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/chf3198/copilot-handoff/blob/HEAD/CONTRIBUTING.md) for details.

**Quick Start for Contributors:**

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please read our [Code of Conduct](https://github.com/chf3198/copilot-handoff/blob/HEAD/.github/CODE_OF_CONDUCT.md) before contributing.

---

## 📜 License

This extension is licensed under the [MIT License](https://github.com/chf3198/copilot-handoff/blob/HEAD/LICENSE).

---

## 💬 Support & Community

<div align="center">

### Need Help?

[![GitHub Issues](https://img.shields.io/github/issues/chf3198/copilot-handoff?style=for-the-badge&logo=github)](https://github.com/chf3198/copilot-handoff/issues)
[![GitHub Discussions](https://img.shields.io/github/discussions/chf3198/copilot-handoff?style=for-the-badge&logo=github)](https://github.com/chf3198/copilot-handoff/discussions)

📧 [Report an issue](https://github.com/chf3198/copilot-handoff/issues) • 
💡 [Request a feature](https://github.com/chf3198/copilot-handoff/issues/new?template=feature_request.md) • 
📖 [Read the docs](https://github.com/chf3198/copilot-handoff#readme)

</div>

---

<div align="center">

### ⭐ Show Your Support

If this extension helps you maintain better Copilot sessions, please consider:
- ⭐ [Starring the repo](https://github.com/chf3198/copilot-handoff)
- 📢 Sharing with your team
- 💬 Leaving a review on the [marketplace](https://marketplace.visualstudio.com/items?itemName=curtisfranks.copilot-handoff)

**Made with ❤️ for the VS Code community**

</div>