Copilot Handoff is a VS Code extension that tracks how long you have been in a GitHub Copilot Chat session and reminds you when to start a fresh conversation. Long AI chat sessions degrade context quality — responses become less accurate as the context window fills with older, less relevant information. The extension shows session duration in the status bar, sends configurable reminders at your chosen threshold, and exports a structured handoff document so your next session has full context on what you were working on. Built with TypeScript and the VS Code Extension API.
|
Long AI chat sessions lead to:
|
Copilot Handoff provides:
|
| Feature | Description |
|---|---|
| Session Duration Tracking | Real-time status bar display. Persists across VS Code restarts. Inactivity auto-reset after 5 minutes. |
| Smart Notifications | Configurable reminder modes: once at threshold, periodic at intervals, or never (tracking only). |
| Context Export | Save session state as a structured Markdown handoff document, copy to clipboard, or use a guided template with sections for tasks, decisions, and next steps. |
| @handoff Chat Participant | @handoff analyze scores your chat health (0–100). @handoff export exports context for a new session. |
| Fully Configurable | Six settings control all thresholds and behaviors. |
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]
G --> B
F --> H[Continue Fresh Session]
@handoff analyze scores your current chat session:
| Score | Status | Recommendation |
|---|---|---|
| 90–100 | 🟢 Excellent | Chat is healthy — continue working |
| 70–89 | 🟡 Good | Monitor for quality issues |
| 50–69 | 🟠 Fair | Consider a handoff soon |
| < 50 | 🔴 Poor | Immediate handoff recommended |
From VS Code Marketplace (recommended)
- Open the Extensions view (
Ctrl+Shift+X/Cmd+Shift+X) - Search for "Copilot Handoff" and click Install
From Command Palette
Press Ctrl+P → type ext install curtisfranks.copilot-handoff → Enter
Manual
Download the .vsix from Releases:
code --install-extension copilot-handoff-*.vsixThe $(pulse) Check Chat Health button is always visible in the status bar. Click it to open Copilot Chat with @handoff analyze pre-filled. Press Enter to see your health report.
Access all features via Ctrl+Shift+P / Cmd+Shift+P:
| Command | Description |
|---|---|
Copilot Handoff: Check Chat Health |
Open chat with @handoff analyze pre-filled |
Copilot Handoff: Show Session Info |
View detailed session information |
Copilot Handoff: Export Chat Context |
Export context with format options |
Copilot Handoff: Reset Session Timer |
Manually reset the timer |
Copilot Handoff: Toggle Tracking |
Enable/disable session tracking |
| Command | Description |
|---|---|
@handoff analyze |
Analyze current chat health with 0–100 scoring |
@handoff export |
Export context for handoff to a new session |
Exported handoff documents include:
- 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
Customize all settings in VS Code Settings (Ctrl+, / Cmd+,). Search for copilot-handoff:
| Setting | Type | Default | Description |
|---|---|---|---|
sessionThresholdMinutes |
number | 30 |
Minutes before showing handoff reminder (5–180) |
notificationFrequency |
string | periodic |
When to show reminders: once, periodic, or never |
periodicReminderMinutes |
number | 10 |
Minutes between periodic reminders (1–60) |
autoExportContext |
boolean | false |
Automatically export context when handoff triggers |
showStatusBar |
boolean | true |
Show session duration in status bar |
trackingEnabled |
boolean | true |
Enable/disable session tracking |
Conservative (less interruption)
Aggressive (frequent handoffs)
{
"copilot-handoff.sessionThresholdMinutes": 15,
"copilot-handoff.notificationFrequency": "periodic",
"copilot-handoff.periodicReminderMinutes": 5
}Silent (tracking only)
{
"copilot-handoff.notificationFrequency": "never",
"copilot-handoff.showStatusBar": true
}- Set realistic thresholds — default 30 minutes works well; adjust to your session rhythm
- Use periodic reminders — keeps context fresh without a single hard stop
- Export before breaks — save context before stepping away from a complex problem
- Document decisions — use the handoff template to capture key choices, not just state
| Requirement | Version |
|---|---|
| VS Code | 1.85.0+ |
| GitHub Copilot | Any (recommended, not required) |
| Platform | Windows, macOS, Linux |
| Issue | Status |
|---|---|
| Session tracking uses general editor activity as proxy for Copilot usage | Planned for v0.3.0 when VS Code exposes Copilot Chat API events |
| Direct Copilot Chat API not fully accessible in all VS Code versions | Depends on VS Code API updates |
Does this extension collect any data?
No. Copilot Handoff stores session timing locally only. It never transmits data, never reads your code, and never reads your chat content — only activity timing.
Will this interrupt my workflow?
No. Notifications can be dismissed, snoozed, or set to "never". The status bar can be hidden. All features are optional.
Do I need GitHub Copilot installed?
No, but it's recommended. The extension works independently, tracking general editor activity.
Can I customize the handoff template?
Currently the template is standard but editable after export. Custom templates are planned — see the Roadmap.
Contributions are welcome! See CONTRIBUTING.md to get started.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit and push, then open a Pull Request
Initial release.
- Session duration tracking with persistent state across VS Code restarts
- Smart notification system (once/periodic/never modes)
- Context export: clipboard, file, and guided Markdown template
@handoffchat participant with 0–100 health scoring- 5-minute inactivity auto-reset
- TypeScript strict mode, zero runtime dependencies
See CHANGELOG.md for complete history.
PolyForm Noncommercial 1.0.0 — free for personal, educational, and non-commercial use. Commercial use requires a paid license. See COMMERCIAL-LICENSE.md or contact curtisfranks@gmail.com.
© 2026 Curtis Franks
{ "copilot-handoff.sessionThresholdMinutes": 60, "copilot-handoff.notificationFrequency": "once" }