feat: add optional GitHub authentication support

- GitHub account linking via VS Code's built-in auth provider
- Auth is fully optional: never auto-prompts, all features work without signing in
- New GitHub Auth tab in Diagnostic panel
- New commands: authenticateGitHub and signOutGitHub
- Session restore on startup uses createIfNone: false (no prompting)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rajbos

README.md

@@ -24,6 +24,8 @@ Track your GitHub Copilot token usage and AI Fluency across VS Code, Visual Stud
 
 Real-time token usage in the status bar, fluency score dashboard, usage analysis, cloud sync, and more.
 
+- **GitHub Authentication (Optional)**: Sign in with your GitHub account to unlock future features. All current functionality works without signing in.
+
 ```bash
 # Install from the VS Code Marketplace
 ext install RobBos.copilot-token-tracker

vscode-extension/CHANGELOG.md

@@ -6,6 +6,11 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how
 
 ## [Unreleased]
 
+### Added
+- GitHub authentication support using VS Code's built-in authentication provider (opt-in, signing in is optional)
+- New commands: "Authenticate with GitHub" and "Sign Out from GitHub"
+- GitHub Auth tab in Diagnostic Report panel showing authentication status
+
 ## [0.0.27] - 2026-04-07
 
 ### ✨ Features & Improvements

vscode-extension/package.json

@@ -124,6 +124,16 @@
         "command": "copilot-token-tracker.showEnvironmental",
         "title": "Show Environmental Impact",
         "category": "AI Engineering Fluency"
+      },
+      {
+        "command": "copilot-token-tracker.authenticateGitHub",
+        "title": "Authenticate with GitHub",
+        "category": "AI Engineering Fluency"
+      },
+      {
+        "command": "copilot-token-tracker.signOutGitHub",
+        "title": "Sign Out from GitHub",
+        "category": "AI Engineering Fluency"
       }
     ],
     "configuration": {

vscode-extension/src/extension.ts

@@ -246,6 +246,9 @@ class CopilotTokenTracker implements vscode.Disposable {
 	// Backend facade instance for accessing table storage data
 	private backend: BackendFacade | undefined;
 
+	// GitHub authentication session (undefined = not signed in)
+	private githubSession: vscode.AuthenticationSession | undefined;
+
 	// Helper method to get repository URL from package.json
 	private getRepositoryUrl(): string {
 		return _getRepositoryUrl();
@@ -826,6 +829,9 @@ class CopilotTokenTracker implements vscode.Disposable {
 		// Load persisted cache from storage
 		this.cacheManager.loadCacheFromStorage();
 
+		// Silently restore GitHub session if user was previously authenticated
+		this.restoreGitHubSession();
+
 		// Check GitHub Copilot extension status
 		this.sessionDiscovery.checkCopilotExtension();
 
@@ -898,6 +904,92 @@ class CopilotTokenTracker implements vscode.Disposable {
 		}
 	}
 
+	/**
+	 * Silently restore a GitHub authentication session on startup.
+	 * Only runs if the user was previously authenticated.
+	 * Uses createIfNone: false to never prompt the user automatically.
+	 */
+	private async restoreGitHubSession(): Promise<void> {
+		try {
+			const wasAuthenticated = this.context.globalState.get<boolean>('github.authenticated', false);
+			if (wasAuthenticated) {
+				this.log('Attempting to restore GitHub authentication session...');
+				const session = await vscode.authentication.getSession('github', ['read:user'], { createIfNone: false });
+				if (session) {
+					this.githubSession = session;
+					this.log(`✅ GitHub session restored for ${session.account.label}`);
+					await this.context.globalState.update('github.username', session.account.label);
+				} else {
+					this.log('GitHub session not found — clearing authenticated state');
+					await this.context.globalState.update('github.authenticated', false);
+					await this.context.globalState.update('github.username', undefined);
+				}
+			}
+		} catch (error) {
+			this.warn('Failed to restore GitHub session: ' + String(error));
+			await this.context.globalState.update('github.authenticated', false);
+			await this.context.globalState.update('github.username', undefined);
+		}
+	}
+
+	/**
+	 * Authenticate with GitHub using VS Code's built-in authentication API.
+	 * Only called when the user explicitly requests it (e.g. clicks "Authenticate").
+	 */
+	public async authenticateWithGitHub(): Promise<void> {
+		try {
+			this.log('Attempting GitHub authentication...');
+			const session = await vscode.authentication.getSession(
+				'github',
+				['read:user'],
+				{ createIfNone: true },
+			);
+			if (session) {
+				this.githubSession = session;
+				this.log(`✅ Successfully authenticated as ${session.account.label}`);
+				vscode.window.showInformationMessage(`GitHub authentication successful! Logged in as ${session.account.label}`);
+				await this.context.globalState.update('github.authenticated', true);
+				await this.context.globalState.update('github.username', session.account.label);
+			}
+		} catch (error) {
+			this.error('GitHub authentication failed:', error);
+			vscode.window.showErrorMessage('Failed to authenticate with GitHub. Please try again.');
+		}
+	}
+
+	/** Sign out from GitHub and clear the persisted authentication state. */
+	public async signOutFromGitHub(): Promise<void> {
+		try {
+			this.log('Signing out from GitHub...');
+			this.githubSession = undefined;
+			await this.context.globalState.update('github.authenticated', false);
+			await this.context.globalState.update('github.username', undefined);
+			this.log('✅ Successfully signed out from GitHub');
+			vscode.window.showInformationMessage('Signed out from GitHub successfully.');
+		} catch (error) {
+			this.error('Failed to sign out from GitHub:', error);
+			vscode.window.showErrorMessage('Failed to sign out from GitHub.');
+		}
+	}
+
+	/** Return the current GitHub authentication status based on the in-memory session. */
+	public getGitHubAuthStatus(): { authenticated: boolean; username?: string } {
+		if (this.githubSession) {
+			return { authenticated: true, username: this.githubSession.account.label };
+		}
+		return { authenticated: false };
+	}
+
+	/** Return true if the user is currently authenticated with GitHub. */
+	public isGitHubAuthenticated(): boolean {
+		return this.githubSession !== undefined;
+	}
+
+	/** Return the live GitHub authentication session, or undefined if not signed in. */
+	public getGitHubSession(): vscode.AuthenticationSession | undefined {
+		return this.githubSession;
+	}
+
 	private async showFluencyScoreNewsBanner(): Promise<void> {
 		const dismissedKey = 'news.fluencyScoreBanner.v1.dismissed';
 		if (this.context.globalState.get<boolean>(dismissedKey)) {
@@ -6785,6 +6877,24 @@ ${hashtag}`;
             });
           }
           break;
+        case "authenticateGitHub":
+          await this.dispatch('authenticateGitHub:diagnostics', async () => {
+            this.log('authenticateGitHub message received from diagnostics webview');
+            await this.authenticateWithGitHub();
+            if (this.diagnosticsPanel) {
+              await this.loadDiagnosticDataInBackground(this.diagnosticsPanel);
+            }
+          });
+          break;
+        case "signOutGitHub":
+          await this.dispatch('signOutGitHub:diagnostics', async () => {
+            this.log('signOutGitHub message received from diagnostics webview');
+            await this.signOutFromGitHub();
+            if (this.diagnosticsPanel) {
+              await this.loadDiagnosticDataInBackground(this.diagnosticsPanel);
+            }
+          });
+          break;
       }
     });
 
@@ -6926,6 +7036,7 @@ ${hashtag}`;
         sessionFolders,
         candidatePaths,
         backendStorageInfo,
+        githubAuth: this.getGitHubAuthStatus(),
       });
 
       this.log("✅ Diagnostic data loaded and sent to webview");
@@ -7677,6 +7788,23 @@ export function activate(context: vscode.ExtensionContext) {
     },
   );
 
+  // Register the GitHub authentication commands
+  const authenticateGitHubCommand = vscode.commands.registerCommand(
+    "copilot-token-tracker.authenticateGitHub",
+    async () => {
+      tokenTracker.log("GitHub authentication command called");
+      await tokenTracker.authenticateWithGitHub();
+    },
+  );
+
+  const signOutGitHubCommand = vscode.commands.registerCommand(
+    "copilot-token-tracker.signOutGitHub",
+    async () => {
+      tokenTracker.log("GitHub sign out command called");
+      await tokenTracker.signOutFromGitHub();
+    },
+  );
+
   // Add to subscriptions for proper cleanup
   context.subscriptions.push(
     refreshCommand,
@@ -7690,6 +7818,8 @@ export function activate(context: vscode.ExtensionContext) {
     showEnvironmentalCommand,
     generateDiagnosticReportCommand,
     clearCacheCommand,
+    authenticateGitHubCommand,
+    signOutGitHubCommand,
     tokenTracker,
   );
 

vscode-extension/src/webview/diagnostics/main.ts

@@ -58,6 +58,11 @@ type BackendStorageInfo = {
   recordCount: number | null;
 };
 
+type GitHubAuthStatus = {
+  authenticated: boolean;
+  username?: string;
+};
+
 type GlobalStateCounters = {
   openCount: number;
   unknownMcpOpenCount: number;
@@ -74,6 +79,7 @@ type DiagnosticsData = {
   backendConfigured?: boolean;
   isDebugMode?: boolean;
   globalStateCounters?: GlobalStateCounters;
+  githubAuth?: GitHubAuthStatus;
 };
 
 type DiagnosticsViewState = {
@@ -694,6 +700,59 @@ function renderDebugTab(counters: GlobalStateCounters | undefined): string {
     </div>`;
 }
 
+function renderGitHubAuthPanel(githubAuth: GitHubAuthStatus | undefined): string {
+  const authenticated = githubAuth?.authenticated ?? false;
+  const username = githubAuth?.username ?? '';
+  const statusColor = authenticated ? '#2d6a4f' : '#666';
+  const statusIcon = authenticated ? '✅' : '⚪';
+  const statusText = authenticated ? 'Authenticated' : 'Not signed in';
+
+  return `
+		<div class="info-box">
+			<div class="info-box-title">🔑 GitHub Authentication</div>
+			<div>
+				Authenticate with GitHub to unlock additional features in future releases.
+				Signing in is completely optional — all current features work without an account.
+			</div>
+		</div>
+
+		<div class="summary-cards">
+			<div class="summary-card" style="border-left: 4px solid ${statusColor};">
+				<div class="summary-label">${statusIcon} Status</div>
+				<div class="summary-value" style="font-size: 16px; color: ${statusColor};">${statusText}</div>
+			</div>
+			${authenticated ? `
+			<div class="summary-card">
+				<div class="summary-label">👤 Signed in as</div>
+				<div class="summary-value" style="font-size: 16px;">${escapeHtml(username)}</div>
+			</div>
+			` : ''}
+		</div>
+
+		<div style="margin-top: 24px;">
+			<p style="color: #999; font-size: 12px; margin-bottom: 16px;">
+				${authenticated
+    ? 'You are signed in with GitHub. Future features such as repository-specific tracking and team collaboration will use this account.'
+    : "Sign in with your GitHub account to unlock future features. This uses VS Code's built-in authentication and will not affect any existing functionality."}
+			</p>
+		</div>
+
+		<div class="button-group">
+			${authenticated ? `
+			<button class="button secondary" id="btn-sign-out-github">
+				<span>🚪</span>
+				<span>Sign Out</span>
+			</button>
+			` : `
+			<button class="button" id="btn-authenticate-github">
+				<span>🔑</span>
+				<span>Authenticate with GitHub</span>
+			</button>
+			`}
+		</div>
+	`;
+}
+
 function renderBackendStoragePanel(
   backendInfo: BackendStorageInfo | undefined,
 ): string {
@@ -974,6 +1033,7 @@ function renderLayout(data: DiagnosticsData): void {
 				<button class="tab" data-tab="sessions">📁 Session Files (${detailedFiles.length})</button>
 				<button class="tab" data-tab="cache">💾 Cache</button>
 				<button class="tab" data-tab="backend">☁️ Azure Storage</button>
+				<button class="tab" data-tab="github">🔑 GitHub Auth</button>
 				<button class="tab" data-tab="display">⚙️ Settings</button>
 				${data.isDebugMode ? '<button class="tab" data-tab="debug">🐛 Debug</button>' : ''}
 			</div>
@@ -1065,6 +1125,9 @@ function renderLayout(data: DiagnosticsData): void {
 			<div id="tab-backend" class="tab-content">
 				${renderBackendStoragePanel(data.backendStorageInfo)}
 			</div>
+			<div id="tab-github" class="tab-content">
+				${renderGitHubAuthPanel(data.githubAuth)}
+			</div>
 			<div id="tab-display" class="tab-content">
 				<div class="info-box">
 					<div class="info-box-title">⚙️ Display Settings</div>
@@ -1125,6 +1188,15 @@ function renderLayout(data: DiagnosticsData): void {
         console.warn("diagnosticDataLoaded received but backendStorageInfo is missing or undefined");
       }
 
+      // Update GitHub auth panel if status is provided
+      if (message.githubAuth !== undefined) {
+        const githubTabContent = document.getElementById("tab-github");
+        if (githubTabContent) {
+          githubTabContent.innerHTML = renderGitHubAuthPanel(message.githubAuth);
+          setupGitHubAuthHandlers();
+        }
+      }
+
       // Update session folders if provided
       if (message.sessionFolders && message.sessionFolders.length > 0) {
         const reportTabContent = document.getElementById("tab-report");
@@ -1383,6 +1455,20 @@ function renderLayout(data: DiagnosticsData): void {
     }
   });
 
+  // Wire up GitHub authentication button handlers
+  function setupGitHubAuthHandlers(): void {
+    document
+      .getElementById("btn-authenticate-github")
+      ?.addEventListener("click", () => {
+        vscode.postMessage({ command: "authenticateGitHub" });
+      });
+    document
+      .getElementById("btn-sign-out-github")
+      ?.addEventListener("click", () => {
+        vscode.postMessage({ command: "signOutGitHub" });
+      });
+  }
+
   // Handle open storage link clicks
   function setupStorageLinkHandlers(): void {
     document.querySelectorAll(".open-storage-link").forEach((link) => {
@@ -1720,6 +1806,7 @@ function renderLayout(data: DiagnosticsData): void {
   setupBackendButtonHandlers();
   setupFileLinks();
   setupStorageLinkHandlers();
+  setupGitHubAuthHandlers();
 
   // Restore active tab from saved state, with fallback to default
   const savedState = vscode.getState();