feat: Add Files Changed Overview (FCO) - Real-time file diff tracking and UI

Files Changed Overview is a new experimental feature that provides real-time tracking of file modifications during AI coding sessions. FCO displays a live diff view in the sidebar, helping users understand what files are being changed by the AI assistant and review changes before accepting them.

  ## Feature Overview

  The FCO system tracks file modifications through git-like checkpoints and provides:
  - Real-time file change tracking with baseline diffs
  - Interactive UI to view, accept, or reject changes
  - Subtask file collection and parent task aggregation
  - Performance optimization with virtualization for large file lists
  - Full internationalization support (15+ languages)

  ## New Files Created

  ### Core Services (`src/services/files-changed/`)

  **FilesChangedManager.ts** - Core file tracking engine
  - Minimal in-memory store for file changes with Map-based storage
  - Tracks files against git checkpoint baselines (default: HEAD)
  - Provides upsert/remove operations for individual file changes
  - Integrates with FileContextTracker for roo_edited events

  **FilesChangedMessageHandler.ts** - Central orchestrator and event handler
  - Manages FCO lifecycle (enable/disable experiment toggle)
  - Handles checkpoint events and file diff processing
  - Orchestrates subtask completion and file collection
  - Implements defensive fallback for missed roo_edited events
  - Provides message passing bridge to webview UI

  **TaskFilesChangedState.ts** - Per-task state management
  - Encapsulates FilesChangedManager instance per task
  - Manages queued child URIs from subtask completion
  - Handles state cloning for task inheritance
  - Provides waiting/checkpoint synchronization flags

  ### Tests (`src/services/files-changed/__tests__/`)

  **FilesChangedManager.test.ts** - Unit tests for core manager
  - Tests file upsert/remove operations and state management
  - Validates baseline checkpoint handling
  - Ensures proper Map-based storage behavior

  **FilesChangedMessageHandler.test.ts** - Integration tests for orchestrator
  - Tests experiment toggle lifecycle and state transitions
  - Validates checkpoint event processing and diff generation
  - Tests subtask completion flow and child file collection
  - Includes comprehensive fallback mechanism testing for missed events

  ### UI Components (`webview-ui/src/components/file-changes/`)

  **FilesChangedOverview.tsx** - React component for sidebar UI
  - Self-managing component with checkpoint event listeners
  - Performance-optimized with virtualization for 50+ files
  - Collapsible file list with expand/collapse state
  - File action buttons (view, accept, reject) with debounced handlers
  - Responsive design with mobile-friendly styling

  ### Internationalization (`webview-ui/src/i18n/locales/*/`)

  **file-changes.json** - Translation files for 15+ languages
  - Supports: en, es, fr, de, it, pt-BR, ru, zh-CN, zh-TW, ja, ko, hi, vi, tr, nl, pl, ca, id
  - Translates UI labels: "Files Changed", "Accept", "Reject", "View Changes", etc.
  - Maintains consistent terminology across all supported languages

  ## Modified Files - Core Integration

  ### Task Management (`src/core/task/Task.ts`)
  - Added FilesChangedState integration to Task class
  - Implemented getFilesChangedState() and disposeFilesChangedState() methods
  - Integrated FCO state management into task lifecycle

  ### Main Provider (`src/core/webview/ClineProvider.ts`)
  - Integrated FilesChangedMessageHandler as core service
  - Added FCO initialization in constructor with proper dependency injection
  - Modified finishSubTask() to await async handleChildTaskCompletion()
  - Updated dispose() to clean up FCO resources

  ### File Context Tracking (`src/core/context-tracking/FileContextTracker.ts`)
  - Enhanced roo_edited event emission to include FCO integration
  - Added file change metadata for better diff tracking
  - Improved event payload structure for FCO consumption

  ### Message Types (`src/shared/ExtensionMessage.ts` & `WebviewMessage.ts`)
  - Added FilesChangedToggle message type for experiment control
  - Added FilesChangedUpdate message type for real-time UI updates
  - Extended message union types to support FCO communication

  ### Experiments (`src/shared/experiments.ts`)
  - Added FILES_CHANGED_OVERVIEW experiment ID and default configuration
  - Integrated with existing experiment framework (disabled by default)
  - Added experiment metadata for UI display

  ### Types (`packages/types/src/`)
  - Added FileChange and FileChangeset interfaces
  - Defined file change operations (edit, create, delete)
  - Added experiment type definitions for FCO

  ### Checkpoint Integration (`src/services/checkpoints/ShadowCheckpointService.ts`)
  - Enhanced checkpoint events to trigger FCO updates
  - Added baseline checkpoint support for diff calculations
  - Improved git diff integration for file change detection

 ## Architecture Highlights

  ### Event-Driven Design
  - FCO listens to checkpoint events from ShadowCheckpointService
  - FileContextTracker emits roo_edited events consumed by FCO
  - WebView receives real-time updates via message passing

  ### Performance Optimizations
  - Virtualization for file lists with 50+ items (10 visible items max)
  - Debounced UI actions to prevent excessive API calls
  - Map-based file storage for O(1) lookup/update operations

  ### Separation of Concerns
  - FilesChangedManager: Pure file state management
  - FilesChangedMessageHandler: Event orchestration and business logic
  - TaskFilesChangedState: Per-task state isolation
  - FilesChangedOverview: UI presentation layer

  ### Defensive Programming
  - Fallback mechanisms for missed file tracking events
  - Graceful error handling for git operations
  - Null-safe state access throughout the codebase
  - Comprehensive edge case testing

Author: playcations

packages/types/src/experiment.ts

@@ -12,6 +12,7 @@ export const experimentIds = [
 	"preventFocusDisruption",
 	"imageGeneration",
 	"runSlashCommand",
+	"filesChangedOverview",
 ] as const
 
 export const experimentIdsSchema = z.enum(experimentIds)
@@ -28,6 +29,7 @@ export const experimentsSchema = z.object({
 	preventFocusDisruption: z.boolean().optional(),
 	imageGeneration: z.boolean().optional(),
 	runSlashCommand: z.boolean().optional(),
+	filesChangedOverview: z.boolean().optional(),
 })
 
 export type Experiments = z.infer<typeof experimentsSchema>

packages/types/src/file-changes.ts

@@ -0,0 +1,21 @@
+export type FileChangeType = "create" | "delete" | "edit"
+
+export interface FileChange {
+	uri: string
+	type: FileChangeType
+	// Note: Checkpoint hashes are for backend use, but can be included
+	fromCheckpoint: string
+	toCheckpoint: string
+	// Line count information for display
+	linesAdded?: number
+	linesRemoved?: number
+}
+
+/**
+ * Represents the set of file changes for the webview.
+ * The `files` property is an array for easy serialization.
+ */
+export interface FileChangeset {
+	baseCheckpoint: string
+	files: FileChange[]
+}

packages/types/src/index.ts

@@ -24,3 +24,4 @@ export * from "./type-fu.js"
 export * from "./vscode.js"
 
 export * from "./providers/index.js"
+export * from "./file-changes.js"

src/core/context-tracking/FileContextTracker.ts

@@ -8,6 +8,7 @@ import fs from "fs/promises"
 import { ContextProxy } from "../config/ContextProxy"
 import type { FileMetadataEntry, RecordSource, TaskMetadata } from "./FileContextTrackerTypes"
 import { ClineProvider } from "../webview/ClineProvider"
+import { EventEmitter } from "events"
 
 // This class is responsible for tracking file operations that may result in stale context.
 // If a user modifies a file outside of Roo, the context may become stale and need to be updated.
@@ -20,7 +21,7 @@ import { ClineProvider } from "../webview/ClineProvider"
 // This class is responsible for tracking file operations.
 // If the full contents of a file are passed to Roo via a tool, mention, or edit, the file is marked as active.
 // If a file is modified outside of Roo, we detect and track this change to prevent stale context.
-export class FileContextTracker {
+export class FileContextTracker extends EventEmitter {
 	readonly taskId: string
 	private providerRef: WeakRef<ClineProvider>
 
@@ -31,6 +32,7 @@ export class FileContextTracker {
 	private checkpointPossibleFiles = new Set<string>()
 
 	constructor(provider: ClineProvider, taskId: string) {
+		super()
 		this.providerRef = new WeakRef(provider)
 		this.taskId = taskId
 	}
@@ -183,6 +185,8 @@ export class FileContextTracker {
 					newEntry.roo_edit_date = now
 					this.checkpointPossibleFiles.add(filePath)
 					this.markFileAsEditedByRoo(filePath)
+					// Emit event for Files Changed Overview
+					this.emit("roo_edited", filePath)
 					break
 
 				// read_tool/file_mentioned: Roo has read the file via a tool or file mention

src/core/task/Task.ts

@@ -112,6 +112,7 @@ import { processUserContentMentions } from "../mentions/processUserContentMentio
 import { getMessagesSinceLastSummary, summarizeConversation } from "../condense"
 import { Gpt5Metadata, ClineMessageWithMetadata } from "./types"
 import { MessageQueueService } from "../message-queue/MessageQueueService"
+import { TaskFilesChangedState } from "../../services/files-changed/TaskFilesChangedState"
 
 import { AutoApprovalHandler } from "./AutoApprovalHandler"
 
@@ -277,6 +278,9 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 	public readonly messageQueueService: MessageQueueService
 	private messageQueueStateChangedHandler: (() => void) | undefined
 
+	// Files Changed Overview state
+	private filesChangedState?: TaskFilesChangedState
+
 	// Streaming
 	isWaitingForFirstChunk = false
 	isStreaming = false
@@ -1598,6 +1602,12 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 			console.error("Error disposing file context tracker:", error)
 		}
 
+		try {
+			this.disposeFilesChangedState()
+		} catch (error) {
+			console.error("Error disposing Files Changed state:", error)
+		}
+
 		try {
 			// If we're not streaming then `abortStream` won't be called.
 			if (this.isStreaming && this.diffViewProvider.isEditing) {
@@ -2924,4 +2934,22 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 			console.error(`[Task] Queue processing error:`, e)
 		}
 	}
+
+	// Files Changed Overview helpers
+
+	public ensureFilesChangedState(): TaskFilesChangedState {
+		if (!this.filesChangedState) {
+			this.filesChangedState = new TaskFilesChangedState()
+		}
+		return this.filesChangedState
+	}
+
+	public getFilesChangedState(): TaskFilesChangedState | undefined {
+		return this.filesChangedState
+	}
+
+	public disposeFilesChangedState(): void {
+		this.filesChangedState?.dispose()
+		this.filesChangedState = undefined
+	}
 }

src/core/webview/ClineProvider.ts

@@ -50,7 +50,7 @@ import { supportPrompt } from "../../shared/support-prompt"
 import { GlobalFileNames } from "../../shared/globalFileNames"
 import type { ExtensionMessage, ExtensionState, MarketplaceInstalledMetadata } from "../../shared/ExtensionMessage"
 import { Mode, defaultModeSlug, getModeBySlug } from "../../shared/modes"
-import { experimentDefault } from "../../shared/experiments"
+import { experimentDefault, EXPERIMENT_IDS } from "../../shared/experiments"
 import { formatLanguage } from "../../shared/language"
 import { WebviewMessage } from "../../shared/WebviewMessage"
 import { EMBEDDING_MODEL_PROFILES } from "../../shared/embeddingModels"
@@ -93,6 +93,7 @@ import type { ClineMessage } from "@roo-code/types"
 import { readApiMessages, saveApiMessages, saveTaskMessages } from "../task-persistence"
 import { getNonce } from "./getNonce"
 import { getUri } from "./getUri"
+import { FilesChangedMessageHandler } from "../../services/files-changed/FilesChangedMessageHandler"
 
 /**
  * https://github.com/microsoft/vscode-webview-ui-toolkit-samples/blob/main/default/weather-webview/src/providers/WeatherViewProvider.ts
@@ -136,6 +137,9 @@ export class ClineProvider
 	private taskCreationCallback: (task: Task) => void
 	private taskEventListeners: WeakMap<Task, Array<() => void>> = new WeakMap()
 	private currentWorkspacePath: string | undefined
+	private lastCheckpointByTaskId: Map<string, string> = new Map()
+	// Files Changed handler
+	private filesChangedHandler: FilesChangedMessageHandler
 
 	private recentTasksCache?: string[]
 	private pendingOperations: Map<string, PendingEditOperation> = new Map()
@@ -177,6 +181,9 @@ export class ClineProvider
 			await this.postStateToWebview()
 		})
 
+		// Initialize Files Changed handler
+		this.filesChangedHandler = new FilesChangedMessageHandler(this)
+
 		// Initialize MCP Hub through the singleton manager
 		McpServerManager.getInstance(this.context, this)
 			.then((hub) => {
@@ -481,12 +488,16 @@ export class ClineProvider
 	// This is used when a subtask is finished and the parent task needs to be
 	// resumed.
 	async finishSubTask(lastMessage: string) {
-		// Remove the last cline instance from the stack (this is the finished
-		// subtask).
+		const childTask = this.getCurrentTask()
+		const parentFromStack = this.clineStack.length > 1 ? this.clineStack[this.clineStack.length - 2] : undefined
+		await this.filesChangedHandler.handleChildTaskCompletion(childTask, parentFromStack)
+
+		const previousTask = this.getCurrentTask()
 		await this.removeClineFromStack()
-		// Resume the last cline instance in the stack (if it exists - this is
-		// the 'parent' calling task).
-		await this.getCurrentTask()?.completeSubtask(lastMessage)
+		const parentTask = this.getCurrentTask()
+
+		await parentTask?.completeSubtask(lastMessage)
+		await this.filesChangedHandler.applyExperimentsToTask(parentTask)
 	}
 	// Pending Edit Operations Management
 
@@ -588,6 +599,7 @@ export class ClineProvider
 		}
 
 		this.clearWebviewResources()
+		this.filesChangedHandler?.dispose(this.getCurrentTask())
 
 		// Clean up cloud service event listener
 		if (CloudService.hasInstance()) {
@@ -845,6 +857,8 @@ export class ClineProvider
 	}
 
 	public async createTaskWithHistoryItem(historyItem: HistoryItem & { rootTask?: Task; parentTask?: Task }) {
+		// Capture current task before removal for potential FCO state transfer
+		const previousTask = this.getCurrentTask()
 		await this.removeClineFromStack()
 
 		// If the history item has a saved mode, restore it and its associated API configuration.
@@ -919,10 +933,17 @@ export class ClineProvider
 
 		await this.addClineToStack(task)
 
+		if (previousTask && previousTask.taskId === task.taskId) {
+			this.filesChangedHandler.transferStateBetweenTasks(previousTask, task)
+		}
+
 		this.log(
 			`[createTaskWithHistoryItem] ${task.parentTask ? "child" : "parent"} task ${task.taskId}.${task.instanceId} instantiated`,
 		)
 
+		// Initialize Files Changed state for this task if setting is enabled
+		await this.filesChangedHandler.applyExperimentsToTask(task)
+
 		// Check if there's a pending edit after checkpoint restoration
 		const operationId = `task-${task.taskId}`
 		const pendingEdit = this.getPendingEditOperation(operationId)
@@ -1149,8 +1170,14 @@ export class ClineProvider
 	 * @param webview A reference to the extension webview
 	 */
 	private setWebviewMessageListener(webview: vscode.Webview) {
-		const onReceiveMessage = async (message: WebviewMessage) =>
-			webviewMessageHandler(this, message, this.marketplaceManager)
+		const onReceiveMessage = async (message: WebviewMessage) => {
+			// Route Files Changed Overview messages first
+			if (this.filesChangedHandler.shouldHandleMessage(message)) {
+				await this.filesChangedHandler.handleMessage(message)
+				return
+			}
+			await webviewMessageHandler(this, message, this.marketplaceManager)
+		}
 
 		const messageDisposable = webview.onDidReceiveMessage(onReceiveMessage)
 		this.webviewDisposables.push(messageDisposable)
@@ -2211,6 +2238,23 @@ export class ClineProvider
 		return this.contextProxy.getValue(key)
 	}
 
+	// FilesChanged Message Handler access
+	public getFilesChangedHandler(): FilesChangedMessageHandler {
+		return this.filesChangedHandler
+	}
+
+	// Track last checkpoint per task for delta-based FilesChanged updates
+	public setLastCheckpointForTask(taskId: string, commitHash: string) {
+		this.lastCheckpointByTaskId.set(taskId, commitHash)
+	}
+
+	/**
+	 * Check if a message should be handled by Files Changed service
+	 */
+	public getLastCheckpointForTask(taskId: string): string | undefined {
+		return this.lastCheckpointByTaskId.get(taskId)
+	}
+
 	public async setValue<K extends keyof RooCodeSettings>(key: K, value: RooCodeSettings[K]) {
 		await this.contextProxy.setValue(key, value)
 	}
@@ -2543,6 +2587,9 @@ export class ClineProvider
 			`[createTask] ${task.parentTask ? "child" : "parent"} task ${task.taskId}.${task.instanceId} instantiated`,
 		)
 
+		// Initialize Files Changed state for this task if setting is enabled
+		await this.filesChangedHandler.applyExperimentsToTask(task)
+
 		return task
 	}
 
@@ -2567,6 +2614,9 @@ export class ClineProvider
 		// Capture the current instance to detect if rehydrate already occurred elsewhere
 		const originalInstanceId = task.instanceId
 
+		// Capture FCO state before task disposal (task.abortTask() will dispose it)
+		const fcoState = task.getFilesChangedState()
+
 		// Begin abort (non-blocking)
 		task.abortTask()
 
@@ -2611,6 +2661,20 @@ export class ClineProvider
 
 		// Clears task again, so we need to abortTask manually above.
 		await this.createTaskWithHistoryItem({ ...historyItem, rootTask, parentTask })
+
+		// Restore FCO state to the new task if we captured it
+		if (fcoState) {
+			const newTask = this.getCurrentTask()
+			if (newTask && newTask.taskId === task.taskId) {
+				const newTaskState = newTask.ensureFilesChangedState()
+				newTaskState.cloneFrom(fcoState)
+				// Ensure the restored task is not waiting (prevents clearFilesChangedDisplay)
+				newTaskState.setWaiting(false)
+				console.log(`[cancelTask] restored FCO state to recreated task ${newTask.taskId}.${newTask.instanceId}`)
+				// Re-trigger FCO display since applyExperimentsToTask may have cleared it
+				await this.filesChangedHandler.applyExperimentsToTask(newTask)
+			}
+		}
 	}
 
 	// Clear the current task without treating it as a subtask.

src/core/webview/__tests__/ClineProvider.spec.ts

@@ -152,6 +152,7 @@ vi.mock("vscode", () => ({
 		showWarningMessage: vi.fn(),
 		showErrorMessage: vi.fn(),
 		onDidChangeActiveTextEditor: vi.fn(() => ({ dispose: vi.fn() })),
+		createTextEditorDecorationType: vi.fn(() => ({ dispose: vi.fn() })),
 	},
 	workspace: {
 		getConfiguration: vi.fn().mockReturnValue({
@@ -188,6 +189,10 @@ vi.mock("../../../api", () => ({
 	buildApiHandler: vi.fn(),
 }))
 
+vi.mock("../../checkpoints", () => ({
+	getCheckpointService: vi.fn(async () => ({})),
+}))
+
 vi.mock("../../prompts/system", () => ({
 	SYSTEM_PROMPT: vi.fn().mockImplementation(async () => "mocked system prompt"),
 	codeMode: "code",

src/core/webview/__tests__/ClineProvider.sticky-mode.spec.ts

@@ -27,6 +27,7 @@ vi.mock("vscode", () => ({
 		showWarningMessage: vi.fn(),
 		showErrorMessage: vi.fn(),
 		onDidChangeActiveTextEditor: vi.fn(() => ({ dispose: vi.fn() })),
+		createTextEditorDecorationType: vi.fn(() => ({ dispose: vi.fn() })),
 	},
 	workspace: {
 		getConfiguration: vi.fn().mockReturnValue({
@@ -148,6 +149,10 @@ vi.mock("../../prompts/system", () => ({
 	codeMode: "code",
 }))
 
+vi.mock("../../checkpoints", () => ({
+	getCheckpointService: vi.fn(async () => ({})),
+}))
+
 vi.mock("../../../api/providers/fetchers/modelCache", () => ({
 	getModels: vi.fn().mockResolvedValue({}),
 	flushModels: vi.fn(),

src/core/webview/webviewMessageHandler.ts

@@ -33,7 +33,7 @@ import {
 	checkoutRestorePayloadSchema,
 } from "../../shared/WebviewMessage"
 import { checkExistKey } from "../../shared/checkExistApiConfig"
-import { experimentDefault } from "../../shared/experiments"
+import { experimentDefault, EXPERIMENT_IDS, experiments } from "../../shared/experiments"
 import { Terminal } from "../../integrations/terminal/Terminal"
 import { openFile } from "../../integrations/misc/open-file"
 import { openImage, saveImage } from "../../integrations/misc/image-handler"
@@ -1942,6 +1942,21 @@ export const webviewMessageHandler = async (
 
 			await updateGlobalState("experiments", updatedExperiments)
 
+			// Simple delegation to FilesChanged handler for universal baseline management
+			try {
+				const currentTask = provider.getCurrentTask()
+				if (currentTask?.taskId) {
+					await provider
+						.getFilesChangedHandler()
+						.handleExperimentToggle(
+							experiments.isEnabled(updatedExperiments, EXPERIMENT_IDS.FILES_CHANGED_OVERVIEW),
+							currentTask,
+						)
+				}
+			} catch (error) {
+				provider.log(`FilesChanged: Error handling experiment toggle: ${error}`)
+			}
+
 			await provider.postStateToWebview()
 			break
 		}