🛡️ Copilot Sentinel

The Context-Aware Token Optimizer for GitHub Copilot

Stop wasting premium AI tokens on redundant project scanning. Copilot Sentinel automatically generates and maintains a project baseline so GitHub Copilot already knows your codebase — before you even ask a question.

🚀 The Problem

GitHub Copilot Pro users in 2026 are limited to 300 premium requests per month (Deep Search, Agentic Mode). Here's what happens without Sentinel:

Scenario	Tokens Wasted
Copilot re-scans your project structure every conversation	~1 premium request each time
You ask "add a new screen" and Copilot searches your entire codebase to understand the architecture	~1-2 premium requests
You switch between files and Copilot loses context	~1 premium request to rebuild
Copilot suggests patterns that don't match your existing architecture	Time wasted fixing + another premium request

A typical developer wastes 30-50% of their monthly quota on Copilot re-discovering things it already knew.

💡 The Solution

Copilot Sentinel acts as a companion layer that sits between your project and GitHub Copilot. It:

Scans your project — detects frameworks, dependencies, entry points, folder structure, and architectural patterns
Generates .github/copilot-instructions.md — the official file that GitHub Copilot reads as project context
Keeps it updated — automatically re-syncs when you save files, but only writes when something actually changes (Delta-Sync)

This means Copilot already knows your tech stack, file structure, and naming conventions before you type a single prompt.

📊 How Much Does This Save?

Token Savings Estimate

Without Sentinel	With Sentinel
Copilot re-scans on every chat session	Copilot reads cached baseline instantly
~3-5 premium requests/day wasted on context rebuilding	0 premium requests wasted
~90-150 premium requests/month wasted	0 wasted
Effective usable quota: 150-210 requests	Effective usable quota: 300 requests

Real-World Savings

Developer Profile	Monthly Waste (Without Sentinel)	Savings (With Sentinel)
Solo developer, 1 project	~50-80 wasted requests	Save 50-80 requests/month
Full-stack dev, 3 projects	~100-150 wasted requests	Save 100-150 requests/month
Team of 5 developers	~500-750 total wasted	Save 500-750 requests/month

Cost Perspective

Copilot Pro costs $10/month for 300 premium requests
Without Sentinel: You effectively pay $10 for ~150-210 usable requests
With Sentinel: You get the full 300 requests for actual coding tasks
ROI: 40-50% more value from your existing Copilot subscription

🔧 How It Works

Architecture

┌─────────────────────────────────────────────────────┐
│                    VS Code                          │
│                                                     │
│  ┌─────────────┐    ┌───────────────────────────┐  │
│  │   Your Code  │    │    Copilot Sentinel        │  │
│  │   (any lang) │───▶│    Extension               │  │
│  └─────────────┘    │                             │  │
│        │             │  1. Detect Framework        │  │
│        │ on save     │  2. Scan Architecture       │  │
│        │ (debounced) │  3. Generate Baseline       │  │
│        ▼             │  4. Delta-Sync (only write  │  │
│  ┌─────────────┐    │     if content changed)     │  │
│  │ .github/     │◀──│                             │  │
│  │ copilot-     │    └───────────────────────────┘  │
│  │ instructions │                                    │
│  │ .md          │───▶ GitHub Copilot reads this     │
│  └─────────────┘     automatically as context       │
└─────────────────────────────────────────────────────┘

Step-by-Step Flow

Extension Activates — When VS Code starts, Sentinel activates after the workspace loads
Initial Scan — Detects your framework(s) by looking for config files (pubspec.yaml, package.json, Cargo.toml, etc.)
Architecture Mapping — Scans for screens, models, routes, services, controllers, blocs, etc. based on the detected framework
Baseline Generation — Creates a structured markdown file with your full project architecture
File Write — Saves to .github/copilot-instructions.md (GitHub Copilot's official context file)
Auto-Sync — When you save a code file, Sentinel re-scans after a 2-second debounce
Delta-Sync — Compares new content with existing file; only writes if something actually changed

Supported Languages & Frameworks

Framework	Config File	Architecture Patterns Detected
Node.js / TypeScript	`package.json`	Routes, Models, Services, Middleware, Components, Config
Flutter / Dart	`pubspec.yaml`	Screens, BLoC/Cubit/Provider, Models, Repositories, Services, Widgets, Config
Python	`requirements.txt`, `pyproject.toml`, `Pipfile`	Views, Models, Services, Config
Rust	`Cargo.toml`	Source Modules, Tests, Benchmarks
Go	`go.mod`	Handlers, Models, Internal, Pkg, Config
Java / Kotlin	`pom.xml`, `build.gradle`	Controllers, Models/Entities, Services, Repositories, Config
PHP	`composer.json`	Controllers, Models, Routes, Middleware, Config
Ruby	`Gemfile`	Controllers, Models, Views, Routes, Services
C# / .NET	`*.csproj`	Controllers, Models, Services, Data/Repositories, Config
Swift	`Package.swift`	Views, Models, ViewModels, Services

Monorepo & Full-Stack Projects

Sentinel automatically detects frameworks in both the workspace root and immediate subdirectories. This means full-stack projects with separate backend/ and frontend/ folders are fully supported out of the box.

Example project structure:

my-project/
├── backend/
│   ├── package.json       ← Sentinel detects Node.js here
│   ├── routes/
│   ├── models/
│   └── services/
├── frontend/
│   ├── package.json       ← Sentinel detects Node.js (React/Vue/etc.) here
│   ├── src/
│   └── public/
└── README.md

What Sentinel generates in the baseline:

## Tech Stack

### Node.js (`backend/package.json`)
- **Project:** my-api
- **Dependencies:** express, mongoose, cors, jsonwebtoken...

### Node.js (`frontend/package.json`)
- **Project:** my-frontend
- **Dependencies:** react, react-dom, axios, tailwindcss...

Copilot will see both stacks and know that backend code uses Express patterns while frontend code uses React patterns — without burning a premium request to figure it out.

Note: Sentinel checks the workspace root first, then scans immediate child directories. It detects each framework type once per location, so a project with backend/package.json and frontend/package.json will show both.

🎯 Features

✅ Available Now (v0.1)

🔍 Baseline Scanner

Feature	Description
Multi-Language Scanner	Auto-detects 10 frameworks and maps project architecture
Auto-Generated Baseline	Creates `.github/copilot-instructions.md` with tech stack, folder structure, entry points, and architecture
Auto-Sync on Save	Re-syncs when code files are saved (debounced, 2s delay)
Delta-Sync	Only writes when content actually changes — no unnecessary file modifications
Immediate Config Sync	Changes to `package.json`, `pubspec.yaml`, etc. trigger instant re-scan
Custom Scan Patterns	Add your own glob patterns via VS Code settings
Exclude Patterns	Exclude specific folders from scanning
Status Bar	Shield icon showing detected framework + sync status + lifetime savings
Output Log	Full scan logs via "Sentinel: Show Output Log"
Open Baseline	Quick command to view the generated baseline file
Configurable	All settings adjustable via VS Code Settings UI

🗄️ Shadow Cache

Feature	Description
Save AI Responses	Store useful Copilot responses locally so you never need to re-prompt for the same answer
Save Code Selections	Right-click any selected code → "Save Selection to Shadow Cache" for instant reuse
Full-Text Search	Search across titles, prompts, responses, tags, file names, and languages in one query
Tag System	Categorise entries with custom tags (e.g., `flutter`, `auth`, `architecture`) and filter by tag
Language Filter	Filter cached snippets by programming language
Copy & Insert	One-click copy to clipboard or insert directly at cursor position in the active editor
Interactive Webview	Beautiful searchable UI panel inside VS Code with syntax highlighting
Export / Import	Export your entire cache as JSON; import caches from teammates or across machines
Cross-Workspace	Cache persists globally — access your saved snippets from any workspace
Configurable Size	Set max entries (default: 500) to control storage usage

📊 Token Savings Dashboard

Feature	Description
Real-Time Tracking	Every saving event is tracked automatically — no manual input required
Lifetime Stats	See total tokens saved, dollar value saved, and days active at a glance
Today / This Month	Instant view of today's savings and current month's accumulation
Daily Bar Chart	Visual chart of savings over the last 30 days
Quota Recovery Gauge	Animated gauge showing what percentage of your monthly 300-request quota Sentinel recovers
Savings Breakdown	Table showing exactly how many tokens each feature saved (baseline, delta-sync, cache, auto-sync)
Recent Activity Feed	Day-by-day activity log with event counts and token totals
Dollar Value Calculation	Converts token savings to dollar value based on Copilot Pro pricing ($10/mo ÷ 300 requests)
Projected Monthly Savings	Estimates your monthly savings based on average daily usage
Local & Private	All data stored locally on your machine — nothing is sent anywhere

💡 Use Cases

Use Case 1: Stop Copilot From Re-Scanning Your Project

Problem: Every time you open a new Copilot Chat session, Copilot spends a premium request scanning your project to understand the architecture, frameworks, and file structure.

How Sentinel Helps:

Sentinel scans your project once and generates .github/copilot-instructions.md
Copilot reads this file automatically at the start of every session (it's an official GitHub feature)
Copilot already knows your tech stack, folder layout, and naming conventions — zero premium requests wasted
When your project changes, Sentinel auto-updates the baseline via Delta-Sync

Savings: ~1 premium request saved per chat session

Use Case 2: Reuse AI Responses Instead of Re-Prompting

Problem: You asked Copilot "How do I set up a BLoC with repository pattern?" last week. Today you need the same pattern for a different feature — but you can't find the old chat. So you ask again, burning another premium request.

How Sentinel Helps:

After getting a useful Copilot response, run "Sentinel: Save to Shadow Cache" (Ctrl+Shift+P)
Give it a title like "Flutter BLoC setup pattern" and add tags like flutter, bloc, architecture
Next time you need it, run "Sentinel: Open Shadow Cache" and search for "bloc" — instant retrieval
Click Copy to clipboard or Insert to paste directly at your cursor

Savings: 1 premium request saved every time you reuse a cached response

Use Case 3: Save Useful Code Snippets From Any File

Problem: You wrote or generated a perfect auth middleware, a tricky regex, or a reusable utility function. You want to save it somewhere searchable — not buried in a random file.

How Sentinel Helps:

Select the code in your editor
Right-click → "Sentinel: Save Selection to Shadow Cache"
Add a title and tags — it automatically records the source file, language, and framework
Later, search the Shadow Cache to find and insert it into any project

Savings: Avoids re-prompting Copilot for code you already have

Problem: Your teammate figured out the perfect prompt to generate a complex query. Now everyone on the team wants the same pattern, but they'd each burn premium requests discovering it independently.

How Sentinel Helps:

Teammate exports their Shadow Cache: click Export in the Shadow Cache webview
Share the JSON file via Slack, email, or your repo
Others run "Sentinel: Import Shadow Cache" → all entries merge into their local cache
The whole team reuses proven patterns without spending a single token

Savings: Multiplied across every team member

Use Case 5: Prove the ROI of Your Copilot Subscription

Problem: Your manager asks "Is Copilot Pro worth $10/month?" — but you have no data to show.

How Sentinel Helps:

Run "Sentinel: Token Savings Dashboard" (Ctrl+Shift+P)
The dashboard shows:
- Lifetime tokens saved — e.g., "247 tokens saved"
- Dollar value — e.g., "$8.23 saved" (calculated from Copilot Pro pricing)
- Quota recovery rate — e.g., "38% of your monthly quota recovered"
- Daily savings chart — visual proof over the last 30 days
- Breakdown by feature — see exactly which Sentinel features saved the most
Screenshot the dashboard and share it with your team or manager

Data tracked: | Event | What It Means | Token Value | |---|---|---| | Baseline Pre-loaded | Copilot didn't need to deep-scan your project | 1.0 request | | Delta-Sync Skip | Baseline was already up-to-date, no unnecessary file write | 0.2 request | | Cache Copy | You reused a cached response instead of re-prompting | 1.0 request | | Cache Insert | You inserted cached code instead of re-prompting | 1.0 request | | Baseline Update | Proactive update keeps Copilot accurate for next session | 0.5 request | | Auto-Sync | Passive sync means Copilot context stays current automatically | 0.3 request |

Use Case 6: Keep Copilot Context Fresh Without Thinking About It

Problem: You add a new file, rename a folder, or install a dependency. Copilot doesn't know about these changes until it wastes a premium request scanning again.

How Sentinel Helps:

Auto-Sync on Save: Every time you save a code file, Sentinel re-scans after a 2-second debounce
Immediate Config Sync: Changes to package.json, pubspec.yaml, go.mod, etc. trigger an instant re-scan (no debounce)
Delta-Sync: Sentinel compares the new scan with the existing baseline — if nothing changed, it skips the write entirely (avoiding Git noise)
The baseline is always accurate, so Copilot always has current context

Savings: ~0.3 tokens per auto-sync event (prevents stale context issues)

Use Case 7: Full-Stack / Monorepo Projects With Backend + Frontend

Problem: Your project has both a backend/ folder (e.g., Express API) and a frontend/ folder (e.g., React app) under one workspace. Copilot doesn't know which framework conventions apply to which folder, so it might suggest React patterns in your API code or Express middleware in your frontend.

How Sentinel Helps:

Sentinel scans the workspace root and immediate subdirectories automatically
It detects backend/package.json (Express + dependencies) and frontend/package.json (React + dependencies) separately
The baseline shows both tech stacks with their respective config paths — Copilot sees the full picture
Architecture scanning picks up routes/models/services from backend/ and components/pages from frontend/
When you ask Copilot to add an API endpoint, it follows the backend patterns; when you ask for a new component, it follows the frontend patterns

Works with any combo:

Node.js backend + React frontend
Python (Django/FastAPI) backend + Vue frontend
Go API + Next.js frontend
Java (Spring) backend + Angular frontend
Any two (or more) frameworks in subdirectories

Savings: ~2 premium requests saved per session (Copilot doesn't need to scan both directories separately)

📦 Installation

From VS Code Marketplace (Coming Soon)

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "Copilot Sentinel"
Click Install

From Source (Development)

git clone https://github.com/your-username/copilot-sentinel.git
cd copilot-sentinel
npm install
npm run compile
# Press F5 in VS Code to launch Extension Development Host

⚙️ Configuration

Open Settings → Extensions → Copilot Sentinel or add to settings.json:

{
  // Enable/disable auto-sync on file save
  "copilotSentinel.autoSyncOnSave": true,

  // Debounce delay (ms) before sync triggers after save
  "copilotSentinel.debounceDelay": 2000,

  // Max files listed per architecture category
  "copilotSentinel.maxFilesPerCategory": 15,

  // File extensions that trigger auto-sync
  "copilotSentinel.fileExtensions": [
    ".ts", ".js", ".tsx", ".jsx", ".py", ".dart",
    ".rs", ".go", ".java", ".kt", ".php", ".rb",
    ".cs", ".swift", ".vue", ".svelte"
  ],

  // Add custom scan patterns
  "copilotSentinel.customScanPatterns": [
    {
      "label": "Mixins",
      "patterns": ["**/mixins/**/*.dart"]
    },
    {
      "label": "Hooks",
      "patterns": ["**/hooks/**/*.{ts,tsx}"]
    }
  ],

  // Exclude additional folders from scanning
  "copilotSentinel.excludePatterns": [
    "**/generated/**",
    "**/tmp/**"
  ],

  // Maximum entries in Shadow Cache (oldest removed first)
  "copilotSentinel.shadowCacheMaxEntries": 500
}

✅ How to Verify It's Working

Quick Check (30 seconds)

Press F5 to launch the Extension Development Host with any project open
Look at the status bar (bottom-right) — you should see 🛡️ Sentinel: [Your Framework]
Open the command palette (Ctrl+Shift+P) → Run "Sentinel: Open Baseline File"
You should see a markdown file with your full project architecture

Detailed Verification

Check	How	Expected Result
Extension activated	Look at status bar	Shield icon with framework name
Baseline file created	Check `.github/copilot-instructions.md` in your project	File exists with full architecture
Tech stack detected	Open baseline file → "Tech Stack" section	Shows project name + dependencies
Folder structure mapped	Open baseline file → "Folder Structure" section	Shows your project's directory tree
Entry points found	Open baseline file → "Entry Points" section	Shows `main.dart`, `index.ts`, etc.
Architecture scanned	Open baseline file → "Architecture" section	Shows screens, models, services, etc. with file paths
Delta-sync works	Click shield button twice without changing code	First click: "Updated", Second click: "Already up to date"
Auto-sync works	Save a `.dart` or `.ts` file	Status bar briefly shows "Scanning..." then returns to framework name
Config sync works	Edit `pubspec.yaml` or `package.json` and save	Immediate re-scan (no debounce delay)
Output log works	Run "Sentinel: Show Output Log"	Shows detailed scan logs with file counts
Shadow Cache	Run "Sentinel: Save to Shadow Cache" → fill in fields	Entry appears in "Sentinel: Open Shadow Cache" webview
Save selection	Select code → right-click → "Save Selection to Shadow Cache"	Entry saved with source file metadata
Token Dashboard	Run "Sentinel: Token Savings Dashboard"	Dashboard opens with lifetime stats, gauge, and chart

Sample Output Log (Healthy)

[1:56:37 AM] 🛡️ Copilot Sentinel activated!
[1:56:37 AM] Starting project scan...
[1:56:37 AM]   ✓ Detected: Flutter / Dart (via pubspec.yaml)
[1:56:38 AM]   Frameworks detected: 1
[1:56:38 AM]   Entry points (Flutter / Dart): lib/main.dart
[1:56:41 AM]   Architecture (Flutter / Dart): 99 files in 7 categories
[1:56:41 AM] Scan complete. Hash: dc7a45556396
[1:56:41 AM] ✅ Baseline written → .github/copilot-instructions.md

🧠 How Copilot Uses the Baseline

GitHub Copilot automatically reads .github/copilot-instructions.md when it's present in a repository. This is an official GitHub feature.

When you ask Copilot a question like:

"Add a new screen for managing invoices"

Without Sentinel, Copilot would:

Use a premium Deep Search to scan your project (~1 token)
Try to understand your architecture (~1 token)
Maybe suggest a pattern that doesn't match your existing code

With Sentinel, Copilot already knows:

✅ You're using Flutter with BLoC pattern
✅ Screens go in lib/[feature]/screens/
✅ State management uses lib/[feature]/bloc/
✅ Models are in lib/models/
✅ Your existing dependencies and naming conventions

So it gives you the correct answer on the first try — no wasted tokens, no wrong patterns.

🎮 Commands Reference

All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Description
Sentinel: Sync Project Baseline	Manually trigger a full project scan and baseline update
Sentinel: Open Baseline File	Open the generated `.github/copilot-instructions.md` in the editor
Sentinel: Show Output Log	Open the Sentinel output channel with detailed scan logs
Sentinel: Save to Shadow Cache	Save a Copilot response (from clipboard or manual input) with title, tags, and metadata
Sentinel: Save Selection to Shadow Cache	Save the currently selected code to the cache (also available via right-click context menu)
Sentinel: Open Shadow Cache	Open the interactive Shadow Cache webview with search, filter, copy, insert, delete, and export
Sentinel: Import Shadow Cache	Import a previously exported Shadow Cache JSON file (merges with existing entries)
Sentinel: Token Savings Dashboard	Open the savings dashboard with lifetime stats, daily chart, breakdown table, and quota gauge

📁 Project Structure

copilot-sentinel/
├── src/
│   ├── extension.ts          # Extension entry point, commands, auto-sync
│   ├── scanner.ts             # Multi-language project scanner (10 frameworks)
│   ├── shadow-cache.ts        # Shadow Cache manager (CRUD, search, export/import)
│   ├── cache-webview.ts       # Shadow Cache interactive webview panel
│   ├── token-tracker.ts       # Token savings tracker with persistence
│   ├── savings-webview.ts     # Token Savings Dashboard webview (charts, gauge)
│   └── test/
│       └── extension.test.ts  # Test suite
├── scripts/
│   └── sentinel-mapper.js     # Legacy CLI scanner (deprecated)
├── dist/
│   └── extension.js           # Compiled output (esbuild)
├── package.json               # Extension manifest
├── tsconfig.json              # TypeScript config
├── esbuild.js                 # Build config
└── README.md                  # This file

🗺️ Roadmap

Phase	Feature	Status
v0.1	Multi-language baseline scanner	✅ Done
v0.1	Auto-sync with delta detection	✅ Done
v0.1	Configurable scan patterns	✅ Done
v0.1	Shadow Cache (searchable history of AI responses + snippets)	✅ Done
v0.1	Shadow Cache export/import (team sharing)	✅ Done
v0.1	Token Savings Dashboard (real-time tracking with charts)	✅ Done
v0.1	Token Tracker (event-based savings persistence)	✅ Done
v0.2	ChatParticipant API (`@sentinel` in Copilot Chat)	🔲 Planned
v0.2	Model Gatekeeper (suggest cheaper models for simple tasks)	🔲 Planned
v1.0	Team Baseline Sync (shared baselines across developers)	🔲 Planned
v1.0	Usage Analytics for team managers	🔲 Planned

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Commit your changes (git commit -m 'Add my feature')
Push to the branch (git push origin feature/my-feature)
Open a Pull Request

📄 License

MIT License

🏢 About

Copilot Sentinel is a Micro SaaS product designed to be a companion app for GitHub Copilot. It doesn't compete with Copilot — it makes Copilot cheaper, faster, and smarter by ensuring it always has the right context.

Built with ❤️ for developers who value every token.

Copilot Sentinel