Copilot Instructions Manager

May 29, 2025 · View on GitHub

A VS Code extension for managing your copilot-instructions.md file with GitHub Gists. This extension allows you to easily upload and download your Copilot instructions to/from a GitHub Gist, keeping them synchronized across different projects and machines.

✨ Features

🚀 One-click Upload: Right-click on copilot-instructions.md to upload it to a GitHub Gist
📥 Easy Download: Right-click in the file explorer to download the latest version
🔄 Version Management: Automatic version tracking and increment on each upload
🎯 Auto-Download on Startup: Automatically checks for newer instructions files when opening workspaces (enabled by default)
⏰ Periodic Sync: Automatically checks for changes at configurable intervals (30 minutes default, enabled by default)
📋 Template Creation: Creates comprehensive instruction templates when no file exists in gist
⚙️ Simple Configuration: Easy setup for GitHub token, Gist ID, and behavior preferences
🔄 Smart Updates: Automatically updates existing Gists or creates new ones
🔒 Secure: Your GitHub token is stored securely in VS Code's configuration

🆕 What's New in v1.6.2

🔄 Real-time File Sync: Automatic sync when files change
- Immediate sync triggers when you save copilot-instructions.md files
- Debounced sync (2-second delay) prevents excessive API calls
- Monitors both .github/copilot-instructions.md and root copilot-instructions.md
- Works alongside periodic sync for comprehensive coverage
⚡ Enhanced Responsiveness: No more waiting for timer intervals
- Files sync immediately when modified, not just every 30 minutes
- Better user experience with instant feedback on changes
- Silent operation with proper error handling and logging

Previous Features (v1.6.1)

🎯 Simplified Interface: Streamlined UI with single sync command
- Removed separate upload/download buttons for cleaner interface
- Only unified "Sync Copilot Instructions" command available
🔄 Smarter Periodic Sync: Enhanced automatic sync behavior
- Periodic sync only downloads newer remote content
- No automatic uploads when local file is newer (use manual sync for uploads)
- More predictable and less intrusive background operation

Previous Features (v1.6.0)

🔄 Unified Sync Command: New intelligent sync command that automatically determines the best action
- Single command handles all sync scenarios: create, upload, download, and conflict resolution
- Smart analysis of local vs remote file states with user-friendly prompts
- Added to command palette, context menus, and keyboard shortcuts
⚡ Enhanced Periodic Sync: Background sync now handles both upload and download scenarios automatically
🤖 Intelligent Sync Logic: Advanced decision-making with content-aware synchronization
📁 Improved Menu Organization: Restructured context menus with logical groupings

Previous Features (v1.5.0)

⏰ Periodic Sync: Automatic background synchronization checks at configurable intervals (1-1440 minutes)
🔕 Notification Control: Configurable notifications - disabled by default for silent operation
🎯 Enhanced Auto-Sync: Smarter background updates that work silently when notifications are off
⚙️ Improved Configuration: New settings for sync intervals and notification preferences
📊 Version Tracking: Each upload automatically increments version numbers with timestamps
🔄 Smart Auto-Updates: Extension checks for newer versions on startup and prompts for updates
📋 Rich Templates: When no instructions exist, creates comprehensive templates with examples for:
- JavaScript/TypeScript, Python, Go, Java
- Docker and Docker Compose
- Security best practices
- Performance optimization
- Testing strategies
- Git workflows and documentation standards
⚙️ Enhanced Configuration: New auto-download setting with user-friendly configuration dialog

🚀 Quick Start

Installation

Option 1: From GitHub Releases (Recommended)

Go to GitHub Releases
Download the latest copilot-instructions-manager-{version}.vsix file

Install using command line:

code --install-extension copilot-instructions-manager-{version}.vsix

Option 2: From VS Code UI

Open VS Code Extensions view (Ctrl+Shift+X)
Click the ... menu → "Install from VSIX..."
Choose the downloaded .vsix file

Initial Setup

Create GitHub Personal Access Token:
- Go to GitHub Token Settings
- Select scope: gist (required)
- Copy the generated token
Configure the extension:
- Open Command Palette (Ctrl+Shift+P)
- Run "Copilot Instructions: Configure GitHub Gist Settings"
- Enter your GitHub token
- Optionally enter an existing Gist ID

Basic Usage

Sync: Right-click on copilot-instructions.md or in explorer → "Sync Copilot Instructions"
Command Palette: Use Ctrl+Shift+P → "Copilot Instructions: Sync Copilot Instructions"

Usage

Syncing Instructions

Right-click on your copilot-instructions.md file or any folder in the explorer
Select "Sync Copilot Instructions" from the "Copilot Instructions" submenu
The extension will intelligently determine the best action:
- Create template if no files exist
- Download if only remote exists
- Upload if only local exists
- Compare and resolve if both exist with differences
Follow the prompts to complete the sync operation

Configuration

Use the Command Palette to run:

Copilot Instructions: Configure GitHub Gist Settings - Set up your GitHub token, Gist ID, and .gitignore preferences

Configuration Options

GitHub Token: Personal Access Token with gist scope
Gist ID: (Optional) ID of existing Gist to use for updates
Auto-manage .gitignore: (Default: enabled) Automatically add copilot-instructions.md to .gitignore when downloading
Auto-download on startup: (Default: enabled) Check for newer instructions when opening workspaces
Periodic sync: (Default: enabled) Automatically check for changes at regular intervals
Real-time sync: (Default: enabled) Enable immediate sync when files are changed
Sync interval: (Default: 30 minutes) How often to check for changes (1-1440 minutes)

Sync Mechanisms

The extension provides two complementary sync mechanisms that can be independently controlled:

🔄 Periodic Sync: Timer-based sync that runs at configurable intervals (default: 30 minutes)
- Ideal for regular background synchronization
- Works even when files aren't being actively modified
- Can be set from 1 minute to 24 hours (1440 minutes)
⚡ Real-time Sync: Immediate sync triggered by file changes (with 2-second debounce)
- Instant response when you save copilot-instructions.md files
- Prevents work loss by syncing changes immediately
- Uses file system watchers for efficient monitoring

Both mechanisms can be enabled simultaneously for comprehensive coverage, or individually based on your workflow preferences.

Requirements

VS Code 1.74.0 or higher
GitHub Personal Access Token with gist scope

Security

Your GitHub token is stored securely in VS Code's configuration. The extension only accesses GitHub's Gist API and does not send data anywhere else.

Troubleshooting

Testing Periodic Sync

If you're unsure whether periodic sync is working:

Check the Output Channel: Open View > Output and select "Copilot Instructions Manager" from the dropdown
Enable Notifications: Set copilotInstructions.showNotifications to true temporarily
Use a Short Interval: Set copilotInstructions.periodicSyncInterval to 1 or 2 minutes for testing
Manual Test: Use the command "Copilot Instructions: Test Periodic Sync (Debug)" from the Command Palette
Check Logs: The output channel will show all sync activity with timestamps

Common Issues

No sync activity: Ensure you have configured both GitHub token and Gist ID
Permissions error: Verify your GitHub token has the gist scope
Network issues: Check your internet connection and GitHub status

Development

For development setup, testing, and release processes, see:

Testing Guide - Comprehensive testing instructions
Release Process - Automated release workflow
GitHub Actions - CI/CD pipeline documentation

Contributing

This extension was created to help manage Copilot instructions across projects. Feel free to suggest improvements or report issues.

License

MIT License