Merge pull request #636 from rajbos/copilot/add-empty-state-guidance

Add empty-state guidance for first-time users in the Details panel

Author: rajbos

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

@@ -151,6 +151,12 @@ function renderShell(
 	const footer = el('div', 'footer', `Last updated: ${lastUpdated.toLocaleString()} · Updates every 5 minutes`);
 
 	const sections = el('div', 'sections');
+
+	const isEmptyState = (stats.today.tokens ?? 0) === 0 && (stats.last30Days.tokens ?? 0) === 0 && (stats.lastMonth.tokens ?? 0) === 0;
+	if (isEmptyState) {
+		sections.append(buildEmptyStateSection());
+	}
+
 	sections.append(buildMetricsSection(stats, projections));
 
 	const editorSection = buildEditorUsageSection(stats);
@@ -677,6 +683,67 @@ function buildModelUsageSection(stats: DetailedStats): HTMLElement | null {
 	return section;
 }
 
+function buildEmptyStateSection(): HTMLElement {
+	const section = el('div', 'section');
+	const inner = el('div', 'empty-state');
+
+	const title = el('div', 'empty-state-title', '👋 Welcome to AI Engineering Fluency');
+
+	const desc = el('p', 'empty-state-description',
+		'This extension tracks AI token usage by reading session log files stored locally by supported tools. No token data has been found yet.'
+	);
+
+	const toolsLabel = document.createElement('p');
+	toolsLabel.className = 'empty-state-description';
+	const toolsLabelStrong = document.createElement('strong');
+	toolsLabelStrong.textContent = 'Supported tools & editors:';
+	toolsLabel.append(toolsLabelStrong);
+
+	const toolsList = document.createElement('ul');
+	toolsList.className = 'empty-state-steps';
+	const toolsTexts = [
+		'💙 VS Code / VS Code Insiders / VSCodium — GitHub Copilot Chat extension',
+		'⚡ Cursor, 🌊 Windsurf — built-in AI chat',
+		'🖥️ Visual Studio 2022+ — GitHub Copilot Chat extension',
+		'🟢 OpenCode, 🦀 Crush — terminal-based coding agents',
+		'🤖 Claude Code — Anthropic\'s CLI coding agent',
+		'💻 Copilot CLI — GitHub Copilot in the terminal',
+	];
+	toolsTexts.forEach(text => {
+		const li = document.createElement('li');
+		li.textContent = text;
+		toolsList.append(li);
+	});
+
+	const stepsLabel = document.createElement('p');
+	stepsLabel.className = 'empty-state-description';
+	const stepsLabelStrong = document.createElement('strong');
+	stepsLabelStrong.textContent = 'To get started:';
+	stepsLabel.append(stepsLabelStrong);
+
+	const steps = document.createElement('ol');
+	steps.className = 'empty-state-steps';
+	const stepTexts = [
+		'Use any of the supported tools or editors listed above to interact with an AI model.',
+		'For GitHub Copilot in VS Code: open the Copilot Chat panel (Ctrl+Alt+I / Cmd+Alt+I) and start a conversation.',
+		'For terminal agents (Claude Code, OpenCode, Copilot CLI): run a coding session in your terminal.',
+		'Click the 🔄 Refresh button above to reload the stats after your first session.',
+	];
+	stepTexts.forEach(text => {
+		const li = document.createElement('li');
+		li.textContent = text;
+		steps.append(li);
+	});
+
+	const note = el('div', 'empty-state-note',
+		'💡 If you have been using one of the supported tools but still see no data, open the Diagnostics panel (🔍 Diagnostics button above) to verify that session files are being discovered correctly.'
+	);
+
+	inner.append(title, desc, toolsLabel, toolsList, stepsLabel, steps, note);
+	section.append(inner);
+	return section;
+}
+
 function buildEstimatesSection(): HTMLElement {
 	const section = el('div', 'section');
 	const heading = el('h3');

vscode-extension/src/webview/details/styles.css

@@ -144,3 +144,45 @@ body {
 	font-size: 11px;
 	margin-top: 6px;
 }
+
+.empty-state {
+	display: flex;
+	flex-direction: column;
+	gap: 12px;
+	padding: 20px;
+}
+
+.empty-state-title {
+	font-size: 15px;
+	font-weight: 700;
+	color: var(--text-primary);
+}
+
+.empty-state-description {
+	color: var(--text-secondary);
+	font-size: 13px;
+	line-height: 1.5;
+	margin: 0;
+}
+
+.empty-state-steps {
+	margin: 0;
+	padding-left: 20px;
+	color: var(--text-secondary);
+	font-size: 13px;
+	line-height: 1.6;
+}
+
+.empty-state-steps li {
+	margin: 4px 0;
+}
+
+.empty-state-note {
+	background: var(--bg-tertiary);
+	border: 1px solid var(--border-subtle);
+	border-radius: 6px;
+	padding: 10px 14px;
+	color: var(--text-secondary);
+	font-size: 12px;
+	line-height: 1.5;
+}