How Roo Code Cloud Integration Syncs Settings Across Sessions

Roo Code synchronizes your configuration across devices by caching cloud settings in VS Code's globalState and refreshing them hourly via a dedicated polling service while the user is authenticated.

Roo Code's cloud integration ensures that your model selections, skill lists, and UI preferences persist seamlessly between VS Code sessions and across different machines. By leveraging a combination of local caching and remote synchronization, the extension provides instant access to your settings even when offline, while keeping them current through periodic background updates.

Core Architecture

The synchronization system relies on three primary components that work together to maintain state consistency between the cloud API and the local VS Code environment.

CloudSettingsService

The CloudSettingsService class, defined in packages/cloud/src/CloudSettingsService.ts, serves as the central authority for retrieving and caching extension settings. It manages the connection to the Roo Code SaaS API and maintains local copies of your configuration.

Key responsibilities include:

• Local caching: Stores settings in VS Code's globalState using the keys organization-settings and user-settings (constants defined on lines 25-26)
• Periodic refresh: Configures a RefreshTimer in the constructor (lines 68-75) that polls the server every 3,600,000ms (one hour) while authenticated
• Event emission: Fires a settings-updated event when new data arrives, signaling other components to refresh

On initialization, the service immediately calls loadCachedSettings (line 79) to restore the last-known configuration from memory, ensuring zero-latency startup.

CloudService

Located in packages/cloud/src/CloudService.ts, this class acts as the bridge between the settings service and the rest of the extension. It subscribes to update events and manages the lifecycle of cloud synchronization based on authentication state.

The service registers a settingsListener on line 108 that forwards settings-updated events to the ExtensionStateContext. It also handles cleanup during logout by stopping the refresh timer and clearing cached data (lines 86-97 and 355).

ExtensionStateContext

The ExtensionStateContext in webview-ui/src/context/ExtensionStateContext.tsx provides the single source of truth for UI components. It maintains the in-memory state including cloudIsAuthenticated (line 34) and the merged settings object (line 488).

When CloudService pushes updates, the context updates its contextValue, causing all consuming components—such as those using useCloudUpsell.ts (line 16)—to re-render with fresh data.

Step-by-Step Synchronization Flow

Understanding the exact sequence of operations helps clarify how Roo Code maintains consistency across sessions:

1. Extension startup: src/extension.ts instantiates CloudService and registers the global settings-updated handler (line 267)

2. Cache hydration: CloudSettingsService reads the Memento keys organization-settings and user-settings into this.settings and this.userSettings, making configuration instantly available before any network request

3. Authentication verification: If authService.getState() === "active-session", the service starts the RefreshTimer (lines 88-90)

4. Remote fetch: The timer triggers fetchSettings(), which performs a GET request to https://app.roocode.com/api/extension-settings (line 115)

5. Validation and storage: The response undergoes Zod validation against organizationSettingsSchema and userSettingsDataSchema (lines 35-45). Valid data updates the cache via context.globalState.update() (lines 389-390)

6. Event propagation: this.emit("settings-updated", {}) fires (line 153), triggering CloudService to update ExtensionStateContext

7. UI refresh: Components using useExtensionState() automatically receive the new values, including the Settings view and cloud upsell hooks

Code Implementation Details

The following excerpts demonstrate the critical synchronization mechanisms in the Roo Code codebase.

Fetching and Caching Remote Settings

When the RefreshTimer triggers or manual refresh occurs, CloudSettingsService executes this flow to retrieve and persist configuration:

// packages/cloud/src/CloudSettingsService.ts (excerpt)
private async fetchSettings(): Promise<boolean> {
  const response = await fetch(`${getRooCodeApiUrl()}/api/extension-settings`);
  const json = await response.json();

  // Validate the shape – Zod guarantees we have a known schema
  const parsed = parseExtensionSettingsResponse(json);
  if (!parsed.success) {
    this.log("[cloud-settings] Invalid extension settings format:", parsed.error);
    return false;
  }

  // Store in VS Code's global state (Memento)
  await this.context.globalState.update(ORGANIZATION_SETTINGS_CACHE_KEY, parsed.data.organization);
  await this.context.globalState.update(USER_SETTINGS_CACHE_KEY, parsed.data.user);

  // Notify the rest of the extension
  this.emit("settings-updated", {} as Record<string, never>);
  return true;
}

Bridging Events to Extension State

The CloudService constructor wires the settings service to the extension's event system:

// packages/cloud/src/CloudService.ts (excerpt)
constructor(context: ExtensionContext, authService: AuthService, ...) {
  ...
  this.settingsListener = (data) => {
    // Forward the event to the extension host
    this.emit("settings-updated", data);
  };

  // Wire the listener once the SettingsService is ready
  this.settingsService.on("settings-updated", this.settingsListener);
}

Consuming Synced State in UI Components

React components access synchronized settings through the context provider:

// webview-ui/src/components/settings/SettingsView.tsx (excerpt)
const { cloudIsAuthenticated, sharingEnabled, ...cachedState } = useExtensionState();

useEffect(() => {
  // Whenever the cloud pushes a new settings payload,
  // `cachedState` is refreshed and the UI reflects the changes.
}, [cachedState]);

Session Management and Cleanup

Roo Code handles session transitions gracefully to prevent stale data or unnecessary network requests:

• Logout: The auth-state-changed handler (lines 86-97) stops the RefreshTimer and invokes removeSettings(), which clears both organization-settings and user-settings from globalState (lines 83-84)
• New device login: When authenticating on a fresh machine, the startup flow reads empty cached values initially, then the timer fetches the latest cloud settings and populates the local cache

Summary

• CloudSettingsService manages the API connection and local caching in VS Code's globalState, refreshing every hour while authenticated
• CloudService bridges the settings service to the extension state and handles authentication lifecycle events
• ExtensionStateContext provides reactive state to UI components, ensuring automatic re-renders when cloud settings change
• The system stores configuration using Memento keys organization-settings and user-settings, surviving extension reloads and IDE restarts
• Zod schemas validate all incoming data to maintain type safety across the distributed system

Frequently Asked Questions

How often does Roo Code sync settings with the cloud?

Roo Code polls the cloud API every 3,600,000 milliseconds (one hour) while the user maintains an active authenticated session. This interval is configured in the CloudSettingsService constructor using the RefreshTimer utility, which only runs when authService.getState() returns "active-session".

Where are cloud settings cached locally?

Settings persist in VS Code's ExtensionContext.globalState (a Memento storage) using the keys organization-settings and user-settings defined in packages/cloud/src/CloudSettingsService.ts. This storage survives extension reloads and IDE restarts, allowing instant access to your configuration even when offline.

What happens to my settings when I log out?

Upon logout, the CloudService triggers cleanup that stops the RefreshTimer and calls removeSettings(), which deletes both cached entries from globalState. This ensures no sensitive configuration remains on the local machine after authentication ends.

Can I use Roo Code on multiple devices simultaneously?

Yes. Because settings store in the Roo Code SaaS backend and cache locally on each device, you can authenticate on multiple machines. Each instance polls independently, so changes made on one device appear on others within the next hourly sync cycle, or immediately upon restarting the extension.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}